mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-25 13:28:56 +00:00
18f9cbcbc4
Sorry translators, but tabs shouldn't have been there in the first place, according to the style guidelines (<http://doc.php.net/tutorial/style.php>). git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@346020 c90b9560-bf6c-de11-be94-00142212c4b1
459 lines
14 KiB
XML
459 lines
14 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- splitted from ./en/functions/image.xml, last change in rev 1.78 -->
|
|
<refentry xml:id="function.exif-read-data" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refnamediv>
|
|
<refname>exif_read_data</refname>
|
|
<refpurpose>Reads the <acronym>EXIF</acronym> headers from an image file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>array</type><methodname>exif_read_data</methodname>
|
|
<methodparam><type>mixed</type><parameter>stream</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>sections</parameter><initializer>&null;</initializer></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>arrays</parameter><initializer>&false;</initializer></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>thumbnail</parameter><initializer>&false;</initializer></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>exif_read_data</function> reads the
|
|
<acronym>EXIF</acronym> headers from an image file. This way you can read meta data
|
|
generated by digital cameras.
|
|
</para>
|
|
<para>
|
|
<acronym>EXIF</acronym> headers tend to be present in JPEG/TIFF images generated by digital
|
|
cameras, but unfortunately each digital camera maker has a different
|
|
idea of how to actually tag their images, so you can't always rely on
|
|
a specific Exif header being present.
|
|
</para>
|
|
<para>
|
|
<literal>Height</literal> and <literal>Width</literal> are computed the
|
|
same way <function>getimagesize</function> does so their values must not be
|
|
part of any header returned. Also, <literal>html</literal> is a
|
|
height/width text string to be used inside normal <acronym>HTML</acronym>.
|
|
</para>
|
|
<para>
|
|
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
|
|
<literal>COMPUTED</literal> section will return both entries
|
|
<literal>Copyright.Photographer</literal> and
|
|
<literal>Copyright.Editor</literal> while the <literal>IFD0</literal>
|
|
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 <literal>COMPUTED</literal> will also contain the entry
|
|
<literal>Copyright</literal> which is either the original copyright string,
|
|
or a comma separated list of the photo and editor copyright.
|
|
</para>
|
|
<para>
|
|
The tag <literal>UserComment</literal> 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 <literal>IFD</literal> section only contains the encoding
|
|
or a byte array. The <literal>COMPUTED</literal> section will store both in
|
|
the entries <literal>UserCommentEncoding</literal> and
|
|
<literal>UserComment</literal>. The entry <literal>UserComment</literal>
|
|
is available in both cases so it should be used in preference to the value
|
|
in <literal>IFD0</literal> section.
|
|
</para>
|
|
<para>
|
|
<function>exif_read_data</function> also validates EXIF data tags according
|
|
to the EXIF specification (<link
|
|
xlink:href="&url.exifspec;">&url.exifspec;</link>, page 20).
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Windows Me/XP can both wipe the Exif headers when connecting to a camera.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>stream</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The location of the image file. This can either be a path to the file
|
|
(stream wrappers are also supported as usual)
|
|
or a stream <type>resource</type>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>sections</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Is a comma separated list of sections that need to be present in file
|
|
to produce a result <type>array</type>. If none of the requested
|
|
sections could be found the return value is &false;.
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry>FILE</entry>
|
|
<entry>FileName, FileSize, FileDateTime, SectionsFound</entry>
|
|
</row>
|
|
<row>
|
|
<entry>COMPUTED</entry>
|
|
<entry>
|
|
html, Width, Height, IsColor, and more if available. Height and
|
|
Width are computed the same way <function>getimagesize</function>
|
|
does so their values must not be part of any header returned.
|
|
Also, <literal>html</literal> is a height/width text string to be used inside normal
|
|
<acronym>HTML</acronym>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>ANY_TAG</entry>
|
|
<entry>Any information that has a Tag e.g. <literal>IFD0</literal>, <literal>EXIF</literal>, ...</entry>
|
|
</row>
|
|
<row>
|
|
<entry>IFD0</entry>
|
|
<entry>
|
|
All tagged data of IFD0. In normal imagefiles this contains
|
|
image size and so forth.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>THUMBNAIL</entry>
|
|
<entry>
|
|
A file is supposed to contain a thumbnail if it has a second <literal>IFD</literal>.
|
|
All tagged information about the embedded thumbnail is stored in
|
|
this section.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>COMMENT</entry>
|
|
<entry>Comment headers of JPEG images.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>EXIF</entry>
|
|
<entry>
|
|
The EXIF section is a sub section of <literal>IFD0</literal>. It contains
|
|
more detailed information about an image. Most of these entries
|
|
are digital camera related.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>arrays</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies whether or not each section becomes an array. The
|
|
<parameter>sections</parameter> <literal>COMPUTED</literal>,
|
|
<literal>THUMBNAIL</literal>, and <literal>COMMENT</literal>
|
|
always become arrays as they may contain values whose names conflict
|
|
with other sections.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>thumbnail</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
When set to &true; the thumbnail itself is read. Otherwise, only the
|
|
tagged data is read.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
It returns an associative <type>array</type> 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,
|
|
<function>exif_read_data</function> will return &false;.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>7.2.0</entry>
|
|
<entry>
|
|
The <parameter>filename</parameter> parameter was renamed to
|
|
<parameter>stream</parameter> and now supports both local files
|
|
or stream resources.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7.2.0</entry>
|
|
<entry>
|
|
Support for the following EXIF formats were added:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
Samsung
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
DJI
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Panasonic
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Sony
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Pentax
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Minolta
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Sigma/Foveon
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
AGFA
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Kyocera
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Ricoh
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Epson
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>4.3.0</entry>
|
|
<entry>
|
|
Can read all embedded <acronym>IFD</acronym> data including arrays
|
|
(returned as such). Also the size of an embedded thumbnail is
|
|
returned in a <literal>THUMBNAIL</literal> subarray, and can
|
|
return thumbnails in <acronym>TIFF</acronym> format. Also, there is
|
|
no longer a maximum length for returned values (not until the memory
|
|
limit has been reached).
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>4.3.0</entry>
|
|
<entry>
|
|
If PHP has <link linkend="ref.mbstring">mbstring</link> support,
|
|
the user comment can automatically change encoding. Also, if the
|
|
user comment uses <literal>Unicode</literal> or <literal>JIS</literal> encoding this encoding will
|
|
automatically be changed according to the exif ini settings in
|
|
&php.ini;
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>4.3.0</entry>
|
|
<entry>
|
|
If the image contains any <literal>IFD0</literal> data then
|
|
<literal>COMPUTED</literal> contains the entry
|
|
<literal>ByteOrderMotorola</literal> which is 0 for
|
|
<literal>little-endian</literal> (intel) and 1 for
|
|
<literal>big-endian</literal> (motorola) byte order. Also,
|
|
<literal>COMPUTED</literal> and <literal>UserComment</literal> no
|
|
longer only contain the first copyright entry if the datatype was
|
|
wrong.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title><function>exif_read_data</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
echo "test1.jpg:<br />\n";
|
|
$exif = exif_read_data('tests/test1.jpg', 'IFD0');
|
|
echo $exif===false ? "No header data found.<br />\n" : "Image contains headers<br />\n";
|
|
|
|
$exif = exif_read_data('tests/test2.jpg', 0, true);
|
|
echo "test2.jpg:<br />\n";
|
|
foreach ($exif as $key => $section) {
|
|
foreach ($section as $name => $val) {
|
|
echo "$key.$name: $val<br />\n";
|
|
}
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The first call fails because the image has no header information.
|
|
</para>
|
|
&example.outputs.similar;
|
|
<screen role="php">
|
|
<![CDATA[
|
|
test1.jpg:
|
|
No header data found.
|
|
test2.jpg:
|
|
FILE.FileName: test2.jpg
|
|
FILE.FileDateTime: 1017666176
|
|
FILE.FileSize: 1240
|
|
FILE.FileType: 2
|
|
FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT
|
|
COMPUTED.html: width="1" height="1"
|
|
COMPUTED.Height: 1
|
|
COMPUTED.Width: 1
|
|
COMPUTED.IsColor: 1
|
|
COMPUTED.ByteOrderMotorola: 1
|
|
COMPUTED.UserComment: Exif test image.
|
|
COMPUTED.UserCommentEncoding: ASCII
|
|
COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger.
|
|
COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
|
|
COMPUTED.Copyright.Editor: Edited by M.Boerger.
|
|
IFD0.Copyright: Photo (c) M.Boerger
|
|
IFD0.UserComment: ASCII
|
|
THUMBNAIL.JPEGInterchangeFormat: 134
|
|
THUMBNAIL.JPEGInterchangeFormatLength: 523
|
|
COMMENT.0: Comment #1.
|
|
COMMENT.1: Comment #2.
|
|
COMMENT.2: Comment #3end
|
|
THUMBNAIL.JPEGInterchangeFormat: 134
|
|
THUMBNAIL.Thumbnail.Height: 1
|
|
THUMBNAIL.Thumbnail.Height: 1
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>exif_read_data</function> with streams available as of PHP 7.2.0</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Open a the file, this should be in binary mode
|
|
$fp = fopen('/path/to/image.jpg', 'rb');
|
|
|
|
if (!$fp) {
|
|
echo 'Error: Unable to open image for reading';
|
|
exit;
|
|
}
|
|
|
|
// Attempt to read the exif headers
|
|
$headers = exif_read_data($fp);
|
|
|
|
if (!$headers) {
|
|
echo 'Error: Unable to read exif headers';
|
|
exit;
|
|
}
|
|
|
|
// Print the 'COMPUTED' headers
|
|
echo 'EXIF Headers:' . PHP_EOL;
|
|
|
|
foreach ($headers['COMPUTED'] as $header => $value) {
|
|
printf(' %s => %s%s', $header, $value, PHP_EOL);
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen role="php">
|
|
<![CDATA[
|
|
EXIF Headers:
|
|
Height => 576
|
|
Width => 1024
|
|
IsColor => 1
|
|
ByteOrderMotorola => 0
|
|
ApertureFNumber => f/5.6
|
|
UserComment =>
|
|
UserCommentEncoding => UNDEFINED
|
|
Copyright => Denis
|
|
Thumbnail.FileType => 2
|
|
Thumbnail.MimeType => image/jpeg
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<note>
|
|
<para>
|
|
If <link linkend="ref.mbstring">mbstring</link> is enabled, exif will attempt to process
|
|
the unicode and pick a charset as specified by
|
|
<link linkend="ini.exif.decode-unicode-motorola">exif.decode_unicode_motorola</link> and
|
|
<link linkend="ini.exif.decode-unicode-intel">exif.decode_unicode_intel</link>. The exif
|
|
extension will not attempt to figure out the encoding on its own, and it is up to the user
|
|
to properly specify the encoding for which to use for decoding by setting one of these two
|
|
ini directives prior to calling <function>exif_read_data</function>.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
If the <parameter>stream</parameter> is used to pass a stream to this function, then the stream
|
|
must be seekable. Note that the file pointer position is not changed after this function returns.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>exif_thumbnail</function></member>
|
|
<member><function>getimagesize</function></member>
|
|
<member><xref linkend="wrappers"/></member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|