reference/exif/functions/exif-read-data.xml
a7421437b658dc4e0455ba8ea7e37a39a530845e
...
...
@@ -4,21 +4,20 @@
4
4
<refentry xml:id="function.exif-read-data" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
5
<refnamediv>
6
6
<refname>exif_read_data</refname>
7
-
<refpurpose>Reads the <acronym>EXIF</acronym> headers from <acronym>JPEG</acronym> or <acronym>TIFF</acronym></refpurpose>
7
+
<refpurpose>Reads the <acronym>EXIF</acronym> headers from an image file</refpurpose>
8
8
</refnamediv>
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>array</type><methodname>exif_read_data</methodname>
13
-
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
14
-
<methodparam choice="opt"><type>string</type><parameter>sections</parameter><initializer>&null;</initializer></methodparam>
15
-
<methodparam choice="opt"><type>bool</type><parameter>arrays</parameter><initializer>false</initializer></methodparam>
16
-
<methodparam choice="opt"><type>bool</type><parameter>thumbnail</parameter><initializer>false</initializer></methodparam>
12
+
<type class="union"><type>array</type><type>false</type></type><methodname>exif_read_data</methodname>
13
+
<methodparam><type class="union"><type>resource</type><type>string</type></type><parameter>file</parameter></methodparam>
14
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>required_sections</parameter><initializer>&null;</initializer></methodparam>
15
+
<methodparam choice="opt"><type>bool</type><parameter>as_arrays</parameter><initializer>&false;</initializer></methodparam>
16
+
<methodparam choice="opt"><type>bool</type><parameter>read_thumbnail</parameter><initializer>&false;</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>
19
19
<function>exif_read_data</function> reads the
20
-
<acronym>EXIF</acronym> headers from a <acronym>JPEG</acronym> or
21
-
<acronym>TIFF</acronym> image file. This way you can read meta data
20
+
<acronym>EXIF</acronym> headers from an image file. This way you can read meta data
22
21
generated by digital cameras.
23
22
</para>
24
23
<para>
...
...
@@ -60,27 +59,23 @@
60
59
to the EXIF specification (<link
61
60
xlink:href="&url.exifspec;">&url.exifspec;</link>, page 20).
62
61
</para>
63
-
<note>
64
-
<para>
65
-
Windows Me/XP can both wipe the Exif headers when connecting to a camera.
66
-
</para>
67
-
</note>
68
62
</refsect1>
69
63
<refsect1 role="parameters">
70
64
&reftitle.parameters;
71
65
<para>
72
66
<variablelist>
73
67
<varlistentry>
74
-
<term><parameter>filename</parameter></term>
68
+
<term><parameter>file</parameter></term>
75
69
<listitem>
76
70
<para>
77
-
The name of the image file being read. This cannot be an
78
-
<acronym>URL</acronym>.
71
+
The location of the image file. This can either be a path to the file
72
+
(stream wrappers are also supported as usual)
73
+
or a stream <type>resource</type>.
79
74
</para>
80
75
</listitem>
81
76
</varlistentry>
82
77
<varlistentry>
83
-
<term><parameter>sections</parameter></term>
78
+
<term><parameter>required_sections</parameter></term>
84
79
<listitem>
85
80
<para>
86
81
Is a comma separated list of sections that need to be present in file
...
...
@@ -141,11 +136,11 @@
141
136
</listitem>
142
137
</varlistentry>
143
138
<varlistentry>
144
-
<term><parameter>arrays</parameter></term>
139
+
<term><parameter>as_arrays</parameter></term>
145
140
<listitem>
146
141
<para>
147
142
Specifies whether or not each section becomes an array. The
148
-
<parameter>sections</parameter> <literal>COMPUTED</literal>,
143
+
<parameter>required_sections</parameter> <literal>COMPUTED</literal>,
149
144
<literal>THUMBNAIL</literal>, and <literal>COMMENT</literal>
150
145
always become arrays as they may contain values whose names conflict
151
146
with other sections.
...
...
@@ -153,7 +148,7 @@
153
148
</listitem>
154
149
</varlistentry>
155
150
<varlistentry>
156
-
<term><parameter>thumbnail</parameter></term>
151
+
<term><parameter>read_thumbnail</parameter></term>
157
152
<listitem>
158
153
<para>
159
154
When set to &true; the thumbnail itself is read. Otherwise, only the
...
...
@@ -173,6 +168,16 @@
173
168
<function>exif_read_data</function> will return &false;.
174
169
</para>
175
170
</refsect1>
171
+

172
+
<refsect1 role="errors">
173
+
&reftitle.errors;
174
+
<para>
175
+
Errors of level <constant>E_WARNING</constant> and/or <constant>E_NOTICE</constant>
176
+
may be raised for unsupported tags or other potential error conditions, but the
177
+
function still tries to read all comprehensible information.
178
+
</para>
179
+
</refsect1>
180
+

176
181
<refsect1 role="changelog">
177
182
&reftitle.changelog;
178
183
<para>
...
...
@@ -186,37 +191,79 @@
186
191
</thead>
187
192
<tbody>
188
193
<row>
189
-
<entry>4.3.0</entry>
194
+
<entry>8.0.0</entry>
190
195
<entry>
191
-
Can read all embedded <acronym>IFD</acronym> data including arrays
192
-
(returned as such). Also the size of an embedded thumbnail is
193
-
returned in a <literal>THUMBNAIL</literal> subarray, and can
194
-
return thumbnails in <acronym>TIFF</acronym> format. Also, there is
195
-
no longer a maximum length for returned values (not until the memory
196
-
limit has been reached)
196
+
<parameter>required_sections</parameter> is nullable now.
197
197
</entry>
198
198
</row>
199
199
<row>
200
-
<entry>4.3.0</entry>
200
+
<entry>7.2.0</entry>
201
201
<entry>
202
-
If PHP has <link linkend="ref.mbstring">mbstring</link> support,
203
-
the user comment can automatically change encoding. Also, if the
204
-
user comment uses <literal>Unicode</literal> or <literal>JIS</literal> encoding this encoding will
205
-
automatically be changed according to the exif ini settings in
206
-
&php.ini;
202
+
The <parameter>file</parameter> parameter now supports both local files
203
+
and stream resources.
207
204
</entry>
208
205
</row>
209
206
<row>
210
-
<entry>4.3.0</entry>
207
+
<entry>7.2.0</entry>
211
208
<entry>
212
-
If the image contains any <literal>IFD0</literal> data then
213
-
<literal>COMPUTED</literal> contains the entry
214
-
<literal>ByteOrderMotorola</literal> which is 0 for
215
-
<literal>little-endian</literal> (intel) and 1 for
216
-
<literal>big-endian</literal> (motorola) byte order. Also,
217
-
<literal>COMPUTED</literal> and <literal>UserComment</literal> no
218
-
longer only contain the first copyright entry if the datatype was
219
-
wrong.
209
+
Support for the following EXIF formats were added:
210
+
<itemizedlist>
211
+
<listitem>
212
+
<simpara>
213
+
Samsung
214
+
</simpara>
215
+
</listitem>
216
+
<listitem>
217
+
<simpara>
218
+
DJI
219
+
</simpara>
220
+
</listitem>
221
+
<listitem>
222
+
<simpara>
223
+
Panasonic
224
+
</simpara>
225
+
</listitem>
226
+
<listitem>
227
+
<simpara>
228
+
Sony
229
+
</simpara>
230
+
</listitem>
231
+
<listitem>
232
+
<simpara>
233
+
Pentax
234
+
</simpara>
235
+
</listitem>
236
+
<listitem>
237
+
<simpara>
238
+
Minolta
239
+
</simpara>
240
+
</listitem>
241
+
<listitem>
242
+
<simpara>
243
+
Sigma/Foveon
244
+
</simpara>
245
+
</listitem>
246
+
<listitem>
247
+
<simpara>
248
+
AGFA
249
+
</simpara>
250
+
</listitem>
251
+
<listitem>
252
+
<simpara>
253
+
Kyocera
254
+
</simpara>
255
+
</listitem>
256
+
<listitem>
257
+
<simpara>
258
+
Ricoh
259
+
</simpara>
260
+
</listitem>
261
+
<listitem>
262
+
<simpara>
263
+
Epson
264
+
</simpara>
265
+
</listitem>
266
+
</itemizedlist>
220
267
</entry>
221
268
</row>
222
269
</tbody>
...
...
@@ -284,6 +331,75 @@ THUMBNAIL.Thumbnail.Height: 1
284
331
</screen>
285
332
</example>
286
333
</para>
334
+
<para>
335
+
<example>
336
+
<title><function>exif_read_data</function> with streams available as of PHP 7.2.0</title>
337
+
<programlisting role="php">
338
+
<![CDATA[
339
+
<?php
340
+
// Open a the file, this should be in binary mode
341
+
$fp = fopen('/path/to/image.jpg', 'rb');
342
+

343
+
if (!$fp) {
344
+
echo 'Error: Unable to open image for reading';
345
+
exit;
346
+
}
347
+

348
+
// Attempt to read the exif headers
349
+
$headers = exif_read_data($fp);
350
+

351
+
if (!$headers) {
352
+
echo 'Error: Unable to read exif headers';
353
+
exit;
354
+
}
355
+

356
+
// Print the 'COMPUTED' headers
357
+
echo 'EXIF Headers:' . PHP_EOL;
358
+

359
+
foreach ($headers['COMPUTED'] as $header => $value) {
360
+
printf(' %s => %s%s', $header, $value, PHP_EOL);
361
+
}
362
+
?>
363
+
]]>
364
+
</programlisting>
365
+
&example.outputs.similar;
366
+
<screen role="php">
367
+
<![CDATA[
368
+
EXIF Headers:
369
+
Height => 576
370
+
Width => 1024
371
+
IsColor => 1
372
+
ByteOrderMotorola => 0
373
+
ApertureFNumber => f/5.6
374
+
UserComment =>
375
+
UserCommentEncoding => UNDEFINED
376
+
Copyright => Denis
377
+
Thumbnail.FileType => 2
378
+
Thumbnail.MimeType => image/jpeg
379
+
]]>
380
+
</screen>
381
+
</example>
382
+
</para>
383
+
</refsect1>
384
+
<refsect1 role="notes">
385
+
&reftitle.notes;
386
+
<note>
387
+
<para>
388
+
If <link linkend="ref.mbstring">mbstring</link> is enabled, exif will attempt to process
389
+
the unicode and pick a charset as specified by
390
+
<link linkend="ini.exif.decode-unicode-motorola">exif.decode_unicode_motorola</link> and
391
+
<link linkend="ini.exif.decode-unicode-intel">exif.decode_unicode_intel</link>. The exif
392
+
extension will not attempt to figure out the encoding on its own, and it is up to the user
393
+
to properly specify the encoding for which to use for decoding by setting one of these two
394
+
ini directives prior to calling <function>exif_read_data</function>.
395
+
</para>
396
+
</note>
397
+
<note>
398
+
<para>
399
+
If the <parameter>file</parameter> is used to pass a stream to this function, then the stream
400
+
must be seekable. Note that the file pointer position is not changed after this function returns.
401
+
</para>
402
+
</note>
287
403
</refsect1>
288
404
<refsect1 role="seealso">
289
405
&reftitle.seealso;
...
...
@@ -291,11 +407,11 @@ THUMBNAIL.Thumbnail.Height: 1
291
407
<simplelist>
292
408
<member><function>exif_thumbnail</function></member>
293
409
<member><function>getimagesize</function></member>
410
+
<member><xref linkend="wrappers"/></member>
294
411
</simplelist>
295
412
</para>
296
413
</refsect1>
297
414
</refentry>
298
-

299
415
<!-- Keep this comment at the end of the file
300
416
Local variables:
301
417
mode: sgml
302
418