From d5c708634f4696118a9d65bf910f9974b3b0f13b Mon Sep 17 00:00:00 2001 From: Philip Olson Date: Sun, 25 Jul 2004 23:08:33 +0000 Subject: [PATCH] Moved exif functions out of ref.image and into new ref.exif, added appropriate files. Modified all exif docs to use new refsect1/reftitle syntax. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@164307 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/exif/configure.xml | 38 ++++ reference/exif/constants.xml | 45 +++++ .../functions/exif-imagetype.xml | 93 ++++----- .../functions/exif-read-data.xml | 163 ++++++++-------- reference/exif/functions/exif-tagname.xml | 51 +++++ .../functions/exif-thumbnail.xml | 67 ++++--- .../functions/read-exif-data.xml | 2 +- reference/exif/ini.xml | 181 ++++++++++++++++++ reference/exif/reference.xml | 63 ++++++ reference/image/ini.xml | 158 +-------------- 10 files changed, 548 insertions(+), 313 deletions(-) create mode 100644 reference/exif/configure.xml create mode 100644 reference/exif/constants.xml rename reference/{image => exif}/functions/exif-imagetype.xml (81%) rename reference/{image => exif}/functions/exif-read-data.xml (82%) create mode 100644 reference/exif/functions/exif-tagname.xml rename reference/{image => exif}/functions/exif-thumbnail.xml (67%) rename reference/{image => exif}/functions/read-exif-data.xml (97%) create mode 100644 reference/exif/ini.xml create mode 100644 reference/exif/reference.xml diff --git a/reference/exif/configure.xml b/reference/exif/configure.xml new file mode 100644 index 0000000000..f151f42363 --- /dev/null +++ b/reference/exif/configure.xml @@ -0,0 +1,38 @@ + + +
+ &reftitle.install; + + To enable exif-support configure PHP with + + + + Windows users must enable both the php_mbstring.dll + and php_exif.dll DLL's in &php.ini;. The + php_mbstring.dll DLL must be loaded + before the php_exif.dll DLL so + adjust your &php.ini; accordingly. + +
+ + + diff --git a/reference/exif/constants.xml b/reference/exif/constants.xml new file mode 100644 index 0000000000..934448e67d --- /dev/null +++ b/reference/exif/constants.xml @@ -0,0 +1,45 @@ + + +
+ &reftitle.constants; + &extension.constants; + + + + + EXIF_USE_MBSTRING + (integer) + + + + + + + + + + + The exif_imagetype lists several related built-in + constants. + +
+ diff --git a/reference/image/functions/exif-imagetype.xml b/reference/exif/functions/exif-imagetype.xml similarity index 81% rename from reference/image/functions/exif-imagetype.xml rename to reference/exif/functions/exif-imagetype.xml index c6ab7b6cdd..f101e5c6e0 100644 --- a/reference/image/functions/exif-imagetype.xml +++ b/reference/exif/functions/exif-imagetype.xml @@ -1,5 +1,5 @@ - + @@ -7,20 +7,35 @@ Determine the type of an image - Description - - intexif_imagetype - stringfilename - + &reftitle.description; + + intexif_imagetype + stringfilename + exif_imagetype reads the first bytes of an image and - checks its signature. When a correct signature is found a constant will be - returned otherwise the return value is &false;. The return value is the - same value that getimagesize returns in index 2 but - this function is much faster. + checks its signature. + + + Support for JPC, JP2, + JPX, JB2, + XBM, and WBMP became available in + PHP 4.3.2. Support for SWC as of PHP 4.3.0. + + - The following constants are defined: + This function can be used to avoid calls to other exif functions with + unsupported file types or in conjunction with + $_SERVER['HTTP_ACCEPT'] to check whether or + not the viewer is able to see a specific image in the browser. + + + + &reftitle.constants; + + The following constants are defined and represent possible + exif_imagetype return values: Imagetype Constants @@ -101,48 +116,38 @@
- - - Support for JPC, JP2, - JPX, JB2, - XBM, and WBMP became available in - PHP 4.3.2. Support for SWC as of PHP 4.3.0. - - + + + &reftitle.returnvalues; - This function can be used to avoid calls to other exif functions with - unsupported file types or in conjunction with - $_SERVER['HTTP_ACCEPT'] to check whether or - not the viewer is able to see a specific image in the browser. + When a correct signature is found the appropriate constant value will be + returned otherwise the return value is &false;. The return value is the + same value that getimagesize returns in index 2 but + this function is much faster. - - - This function is only available if PHP is compiled using - . - - - - - This function does not require the GD image library. - - - - <function>exif_imagetype</function> example - + + + &reftitle.examples; + + + <function>exif_imagetype</function> example + ]]> - - - - See also getimagesize. - + + + + + + &reftitle.seealso; + + getimagesize + diff --git a/reference/image/functions/exif-read-data.xml b/reference/exif/functions/exif-read-data.xml similarity index 82% rename from reference/image/functions/exif-read-data.xml rename to reference/exif/functions/exif-read-data.xml index 88ad22aa9d..d50a1be8e9 100644 --- a/reference/image/functions/exif-read-data.xml +++ b/reference/exif/functions/exif-read-data.xml @@ -1,15 +1,14 @@ - + exif_read_data Reads the EXIF headers from JPEG - or TIFF. This way you can read meta data generated by digital - cameras. + or TIFF - Description + &reftitle.description; arrayexif_read_data stringfilename @@ -19,10 +18,9 @@ The exif_read_data function reads the - EXIF headers from a JPEG or TIFF image file. It returns an associative - array where the indexes are the header names and the values - are the values associated with those headers. If no data can be returned - the result is &false;. + EXIF headers from a JPEG or + TIFF image file. This way you can read meta data + generated by digital cameras. filename is the name of the file to read. This @@ -76,7 +74,7 @@ arrays specifies whether or not each section becomes an array. The sections COMPUTED, - THUMBNAIL and COMMENT allways + THUMBNAIL and COMMENT always become arrays as they may contain values whose names are conflict with other sections. @@ -97,13 +95,80 @@ url="&url.winexif;">&url.winexif;. + + + If the image contains any IFD0 data then COMPUTED contains the entry + ByteOrderMotorola which is 0 for little-endian (intel) and 1 for + big-endian (motorola) byte order. This was added in PHP 4.3.0. + + + When an Exif header contains a Copyright note this itself can contain two + values. As the solution is inconsistent in the Exif 2.10 standard the COMPUTED + section will return both entries Copyright.Photographer + and Copyright.Editor while the IFD0 sections contains + the byte array with the NULL character that splits both entries. Or just the + first entry if the datatype was wrong (normal behaviour of Exif). The + COMPUTED will contain also an entry Copyright Which + is either the original copyright string or it is a comma separated list of + photo and editor copyright. + + + + + The tag UserComment has the same problem as the Copyright tag. It can store + two values first the encoding used and second the value itself. If so the + IFD section only contains the encoding or a byte array. The COMPUTED section + will store both in the entries UserCommentEncoding and + UserComment. The entry UserComment + is available in both cases so it should be used in preference to the value + in IFD0 section. + + + If the user comment uses Unicode or JIS encoding and the module mbstring is + available this encoding will automatically changed according to the exif + ini settings in the &php.ini;. This was added in PHP 4.3.0. + + + + + Height and Width are computed the same way getimagesize + does so their values must not be part of any header returned. Also html is + a height/width text string to be used inside normal HTML. + + + + + Starting from PHP 4.3.0, the function can read all embedded + IFD data including arrays (returned as such). Also + the size of an embedded thumbnail is returned in + THUMBNAIL subarray and the function + exif_read_data can return thumbnails in + TIFF format. Also as of PHP 4.3.0 there is no longer + a maximum length for returned values (not until memory limit is reached). + + + + Since PHP 4.3,0 user comment can automatically change encoding if PHP was + compiled using . + + + + &reftitle.returnvalues; + + It returns an associative array where the array indexes are + the header names and the array values are the values associated with + those headers. If no data can be returned, + exif_read_data will return &false;. + + + + &reftitle.examples; <function>exif_read_data</function> example \n"; $exif = exif_read_data('tests/test1.jpg', 'IFD0'); echo $exif===false ? "No header data found.
\n" : "Image contains headers
"; @@ -155,75 +220,13 @@ THUMBNAIL.Thumbnail.Height: 1 - - - If the image contains any IFD0 data then COMPUTED contains the entry - ByteOrderMotorola which is 0 for little-endian (intel) and 1 for - big-endian (motorola) byte order. This was added in PHP 4.3. - - - When an Exif header contains a Copyright note this itself can contain two - values. As the solution is inconsistent in the Exif 2.10 standard the COMPUTED - section will return both entries Copyright.Photographer - and Copyright.Editor while the IFD0 sections contains - the byte array with the NULL character that splits both entries. Or just the - first entry if the datatype was wrong (normal behaviour of Exif). The - COMPUTED will contain also an entry Copyright Which - is either the original copyright string or it is a comma separated list of - photo and editor copyright. - - - - - The tag UserComment has the same problem as the Copyright tag. It can store - two values first the encoding used and second the value itself. If so the - IFD section only contains the encoding or a byte array. The COMPUTED section - will store both in the entries UserCommentEncoding and - UserComment. The entry UserComment - is available in both cases so it should be used in preference to the value - in IFD0 section. - - - If the user comment uses Unicode or JIS encoding and the module mbstring is - available this encoding will automatically changed according to the exif - ini settings in the &php.ini;. This was added in PHP 4.3. - - - - - Height and Width are computed the same way getimagesize - does so their values must not be part of any header returned. Also html is - a height/width text string to be used inside normal HTML. - - - - - Starting from PHP 4.3 the function can read all embedded IFD - data including arrays (returned as such). Also the size of an embedded thumbnail - is returned in THUMBNAIL subarray and the function - exif_read_data can return thumbnails in TIFF - format. Last but not least there is no longer a maximum length for returned - values (not until memory limit is reached). - - - - - This function is only available in PHP 4 compiled using - . - Its functionality and behaviour has changed in PHP 4.2. Earlier versions - are very unstable. - - - Since PHP 4.3 user comment can automatically change encoding if PHP 4 was - compiled using . - - - This function does not require the GD image library. - - - See also exif_thumbnail and getimagesize. - - + + + &reftitle.seealso; + + exif_thumbnail&listendand; + getimagesize. + @@ -246,4 +249,4 @@ End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 ---> +--> \ No newline at end of file diff --git a/reference/exif/functions/exif-tagname.xml b/reference/exif/functions/exif-tagname.xml new file mode 100644 index 0000000000..0d65d943cc --- /dev/null +++ b/reference/exif/functions/exif-tagname.xml @@ -0,0 +1,51 @@ + + + + + exif_tagname + Get the header name for an index + + + &reftitle.description; + + stringexif_tagname stringindex + + + &warn.undocumented.func; + + + + &reftitle.returnvalues; + + Returns &false; if index is undefined otherwise + the header name is returned. + + + + &reftitle.seealso; + + exif_imagetype. + + + + + diff --git a/reference/image/functions/exif-thumbnail.xml b/reference/exif/functions/exif-thumbnail.xml similarity index 67% rename from reference/image/functions/exif-thumbnail.xml rename to reference/exif/functions/exif-thumbnail.xml index 9ea41d6dd2..95c379af84 100644 --- a/reference/image/functions/exif-thumbnail.xml +++ b/reference/exif/functions/exif-thumbnail.xml @@ -1,5 +1,5 @@ - + @@ -7,18 +7,21 @@ Retrieve the embedded thumbnail of a TIFF or JPEG image - Description - - stringexif_thumbnail - stringfilename - int&width - int&height - int&imagetype - + &reftitle.description; + + stringexif_thumbnail + stringfilename + int&width + int&height + int&imagetype + - exif_thumbnail reads the embedded thumbnail of - a TIFF or JPEG image. If the image contains no thumbnail &false; - will be returned. + exif_thumbnail reads the embedded thumbnail of a + TIFF or JPEG image. + + + If you want to deliver thumbnails through this function, you should send + the mimetype information using the header function. The parameters width, @@ -30,10 +33,20 @@ height are set. - If you want to deliver thumbnails through this function, you should send - the mimetype information using the header function. - The following example demonstrates this: + Starting from version PHP 4.3.0, the function + exif_thumbnail can return thumbnails in + TIFF format. + + + &reftitle.returnvalues; + + If the image contains no thumbnail, &false; will be returned. Otherwise + the embedded thumbnail is returned. + + + + &reftitle.examples; <function>exif_thumbnail</function> example @@ -58,27 +71,13 @@ if ($image!==false) { + + + &reftitle.seealso; - Starting from version PHP 4.3.0, the function - exif_thumbnail can return thumbnails in - TIFF format. - - - - This function is only available in PHP 4 compiled using - . - Its functionality and behaviour has changed in PHP 4.2.0 - - - - - This function does not require the GD image library. - - - - See also exif_read_data and + exif_read_data&listendand; image_type_to_mime_type. - + diff --git a/reference/image/functions/read-exif-data.xml b/reference/exif/functions/read-exif-data.xml similarity index 97% rename from reference/image/functions/read-exif-data.xml rename to reference/exif/functions/read-exif-data.xml index fbe5233277..4c9cc0008b 100644 --- a/reference/image/functions/read-exif-data.xml +++ b/reference/exif/functions/read-exif-data.xml @@ -1,5 +1,5 @@ - + diff --git a/reference/exif/ini.xml b/reference/exif/ini.xml new file mode 100644 index 0000000000..d1bc130b61 --- /dev/null +++ b/reference/exif/ini.xml @@ -0,0 +1,181 @@ + + +
+ &reftitle.runtime; + &extension.runtime; + + Exif supports automatically conversion for Unicode and JIS + character encodings of user comments when module + mbstring + is available. This is done by first decoding the comment + using the specified characterset. The result is then encoded + with another characterset which should match your + HTTP output. + + Exif configuration options + + + + Name + Default + Changeable + + + + + exif.encode_unicode + "ISO-8859-15" + PHP_INI_ALL + + + exif.decode_unicode_motorola + "UCS-2BE" + PHP_INI_ALL + + + exif.decode_unicode_intel + "UCS-2LE" + PHP_INI_ALL + + + exif.encode_jis + "" + PHP_INI_ALL + + + exif.decode_jis_motorola + "JIS" + PHP_INI_ALL + + + exif.decode_jis_intel + "JIS" + PHP_INI_ALL + + + +
+ For further details and definition of the PHP_INI_* constants see + ini_set. + + + &ini.descriptions.title; + + + + + + exif.encode_unicode + string + + + + exif.encode_unicode defines the + characterset UNICODE user comments are handled. + This defaults to ISO-8859-15 which should work for + most non Asian countries. The setting can be empty + or must be an encoding supported by mbstring. If it + is empty the current internal encoding of mbstring is + used. + + + + + + exif.decode_unicode_motorola + string + + + + exif.decode_unicode_motorola defines + the image internal characterset for Unicode encoded user + comments if image is in motorola byte order (big-endian). + This setting cannot be empty but you can specify a list + of encodings supported by mbstring. The default is UCS-2BE. + + + + + + exif.decode_unicode_intel + string + + + + exif.decode_unicode_intel defines + the image internal characterset for Unicode encoded user + comments if image is in intel byte order (little-endian). + This setting cannot be empty but you can specify a list + of encodings supported by mbstring. The default is UCS-2LE. + + + + + + exif.encode_jis + string + + + + exif.encode_jis defines the + characterset JIS user comments are handled. + This defaults to an empty value which forces + the functions to use the current internal encoding + of mbstring. + + + + + + exif.decode_jis_motorola + string + + + + exif.decode_jis_motorola defines + the image internal characterset for JIS encoded user + comments if image is in motorola byte order (big-endian). + This setting cannot be empty but you can specify a list + of encodings supported by mbstring. The default is JIS. + + + + + + exif.decode_jis_intel + string + + + + exif.decode_jis_intel defines + the image internal characterset for JIS encoded user + comments if image is in intel byte order (little-endian). + This setting cannot be empty but you can specify a list + of encodings supported by mbstring. The default is JIS. + + + + + +
+ + \ No newline at end of file diff --git a/reference/exif/reference.xml b/reference/exif/reference.xml new file mode 100644 index 0000000000..d355662348 --- /dev/null +++ b/reference/exif/reference.xml @@ -0,0 +1,63 @@ + + + + Exif Functions + Exif + + +
+ &reftitle.intro; + + With the exif extension you are able to work with image meta data. For + example, you may use exif functions to read meta data of pictures taken + from digital cameras by working with information stored in the headers of + the JPEG and TIFF images. + +
+ +
+ &reftitle.required; + + Your PHP must be compiled in with --enable-exif. + The GD library is not required for the exif + extension. Window users must also have the + mbstring extension enabled. + +
+ + &reference.exif.configure; + + &reference.exif.ini; + +
+ &reftitle.resources; + &no.resource; +
+ + &reference.exif.constants; + + + + &reference.exif.functions; + + + diff --git a/reference/image/ini.xml b/reference/image/ini.xml index 2ad244742d..b8120b9515 100644 --- a/reference/image/ini.xml +++ b/reference/image/ini.xml @@ -1,164 +1,14 @@ - +
&reftitle.runtime; - &extension.runtime; - Exif supports automatically conversion for Unicode and JIS - character encodings of user comments when module - mbstring - is available. This is done by first decoding the comment - using the specified characterset. The result is then encoded - with another characterset which should match your - HTTP output. - - Exif configuration options - - - - Name - Default - Changeable - - - - - exif.encode_unicode - "ISO-8859-15" - PHP_INI_ALL - - - exif.decode_unicode_motorola - "UCS-2BE" - PHP_INI_ALL - - - exif.decode_unicode_intel - "UCS-2LE" - PHP_INI_ALL - - - exif.encode_jis - "" - PHP_INI_ALL - - - exif.decode_jis_motorola - "JIS" - PHP_INI_ALL - - - exif.decode_jis_intel - "JIS" - PHP_INI_ALL - - - -
- For further details and definition of the PHP_INI_* constants see - ini_set. - - - &ini.descriptions.title; - - - - - - exif.encode_unicode - string - - - - exif.encode_unicode defines the - characterset UNICODE user comments are handled. - This defaults to ISO-8859-15 which should work for - most non Asian countries. The setting can be empty - or must be an encoding supported by mbstring. If it - is empty the current internal encoding of mbstring is - used. - - - - - - exif.decode_unicode_motorola - string - - - - exif.decode_unicode_motorola defines - the image internal characterset for Unicode encoded user - comments if image is in motorola byte order (big-endian). - This setting cannot be empty but you can specify a list - of encodings supported by mbstring. The default is UCS-2BE. - - - - - - exif.decode_unicode_intel - string - - - - exif.decode_unicode_intel defines - the image internal characterset for Unicode encoded user - comments if image is in intel byte order (little-endian). - This setting cannot be empty but you can specify a list - of encodings supported by mbstring. The default is UCS-2LE. - - - - - - exif.encode_jis - string - - - - exif.encode_jis defines the - characterset JIS user comments are handled. - This defaults to an empty value which forces - the functions to use the current internal encoding - of mbstring. - - - - - - exif.decode_jis_motorola - string - - - - exif.decode_jis_motorola defines - the image internal characterset for JIS encoded user - comments if image is in motorola byte order (big-endian). - This setting cannot be empty but you can specify a list - of encodings supported by mbstring. The default is JIS. - - - - - - exif.decode_jis_intel - string - - - - exif.decode_jis_intel defines - the image internal characterset for JIS encoded user - comments if image is in intel byte order (little-endian). - This setting cannot be empty but you can specify a list - of encodings supported by mbstring. The default is JIS. - - - - + There are no image specific configurations but you may be interested in the + exif extension directives.
+