<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: f57352dd7a678230f929e1bac0d4a9189631cf16 Maintainer: tmn Status: ready -->

<!-- Reviewed: no -->

<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>

Читает заголовки <acronym>EXIF</acronym> из файлов изображений

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>array</type><type>false</type></type><methodname>exif_read_data</methodname>

<methodparam><type class="union"><type>resource</type><type>string</type></type><parameter>file</parameter></methodparam>

<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>required_sections</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type>bool</type><parameter>as_arrays</parameter><initializer>&false;</initializer></methodparam>

<methodparam choice="opt"><type>bool</type><parameter>read_thumbnail</parameter><initializer>&false;</initializer></methodparam>

</methodsynopsis>

<para>

Функция <function>exif_read_data</function> читает заголовки <acronym>EXIF</acronym>

из файлов изображений. Так читают метаданные, которые генерируют цифровые фотоаппараты.

</para>

<para>

По идее, <acronym>EXIF</acronym>-заголовки должны идти первыми в JPEG- или TIFF-файлах,

которые генерируют фотоаппараты. Но, к сожалению, каждый производитель по-своему

представляет, как компоновать метаданные изображения.

Поэтому будьте готовы к ситуации, когда перед Exif-заголовком есть ещё что-то.

</para>

<para>

Значения <literal>Height</literal> и <literal>Width</literal> функция вычисляет аналогично

вычислениям функции <function>getimagesize</function>, так что эти параметры не обязаны

присутствовать в заголовке. <literal>html</literal> — текстовая строка, которая задаёт

высоту и ширину, которую можно использовать в обычном <acronym>HTML</acronym>.

</para>

<para>

Если Exif-заголовок содержит сообщение об авторских правах, само

сообщение может содержать 2 значения. Стандарт Exif 2.10 не описывает эту ситуацию,

поэтому раздел <literal>COMPUTED</literal> будет содержать оба

этих значения в полях <literal>Copyright.Photographer</literal> и

<literal>Copyright.Editor</literal>. В то же время разделы

<literal>IFD0</literal> будут содержать массив байтов с NULL-символом в качестве

разделителя этих двух значений либо только первое значение, если тип файла

определился неверно (нормальная ситуация для Exif). Раздел

<literal>COMPUTED</literal> будет также содержать <literal>Copyright</literal>,

который бывает либо исходной строкой, либо списком из владельца

фотографии и редактора через запятую.

</para>

<para>

Тег <literal>UserComment</literal> содержит те же проблемы, что и Copyright.

Он может хранить 2 значения. Первое — кодировку, второе —

само значение. В этом случае раздел <literal>IFD</literal> содержит либо

кодировку, либо массив байтов. Раздел <literal>COMPUTED</literal> будет хранить

оба этих значения в полях <literal>UserCommentEncoding</literal> и

<literal>UserComment</literal>. Содержимое тега <literal>UserComment</literal>

будет доступно в любом случае, поэтому лучше использовать этот тег вместо

раздела <literal>IFD0</literal>.

</para>

<para>

Также <function>exif_read_data</function> проверяет EXIF-теги на соответствие

спецификации EXIF (<link

xlink:href="&url.exifspec;">&url.exifspec;</link>, стр. 20).

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>file</parameter></term>

<listitem>

<para>

Местоположение файла с изображением. Может быть как путём к файлу,

так и потоковым ресурсом (можно использовать обёртки).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>required_sections</parameter></term>

<listitem>

<para>

Список разделённых запятой разделов, которые должны быть представлены

в результирующем массиве (<type>array</type>). Если ни один из разделов найти

не удастся, функция вернёт &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, и другие. Height и

Width вычисляются аналогично <function>getimagesize</function>,

поэтому их не обязательно включать в заголовок.

<literal>html</literal> — текстовая строка, задающая

высоту/ширину, которую можно использовать в обычном

<acronym>HTML</acronym>.

</entry>

</row>

<row>

<entry>ANY_TAG</entry>

<entry>Любая информация заключённая в тег, например,

<literal>IFD0</literal>, <literal>EXIF</literal>, ...</entry>

</row>

<row>

<entry>IFD0</entry>

<entry>

Все данные тега IFD0. В обычных изображениях в нем хранится размер

изображения.

</entry>

</row>

<row>

<entry>THUMBNAIL</entry>

<entry>

Если файл содержит второй раздел <literal>IFD</literal>, то считается,

что у изображения есть эскиз. Вся информация об эскизе хранится в этом

разделе.

</entry>

</row>

<row>

<entry>COMMENT</entry>

<entry>Заголовки комментариев JPEG изображений.</entry>

</row>

<row>

<entry>EXIF</entry>

<entry>

Раздел EXIF является подразделом <literal>IFD0</literal>. Он содержит

более детальную информацию об изображении. Большинство его записей

зависят от фотоаппарата.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>as_arrays</parameter></term>

<listitem>

<para>

Определяет, формировать ли разделы в виде массивов. Разделы

<parameter>required_sections</parameter>, <literal>COMPUTED</literal>,

<literal>THUMBNAIL</literal> и <literal>COMMENT</literal> всегда

делаются массивами, так как они могут содержать значения, имена которых

будут конфликтовать с именами в других разделах.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>read_thumbnail</parameter></term>

<listitem>

<para>

Если &true;, будет прочитан сам эскиз. В противном случае будет прочитана

только информация в тегах.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Возвращает ассоциативный массив (<type>array</type>), в котором ключами будут

имена заголовков, а значениями — значения соответствующие этим заголовкам.

Если никаких данных вернуть нельзя, <function>exif_read_data</function>

вернёт &false;.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

Ошибки уровня <constant>E_WARNING</constant> и/или <constant>E_NOTICE</constant>

могут возникать для неподдерживаемых тегов или других потенциальных условий ошибки, но функция

всё равно пытается прочитать всю понятную информацию.

</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>8.0.0</entry>

<entry>

<parameter>required_sections</parameter> теперь допускает значение null.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

Параметр <parameter>file</parameter> переименовали в

<parameter>stream</parameter> и принимает как локальный путь

к файлу, так и потоковый ресурс.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

<para>

Добавили поддержку следующих форматов EXIF:

<simplelist>

<member>Samsung</member>

<member>DJI</member>

<member>Panasonic</member>

<member>Sony</member>

<member>Pentax</member>

<member>Minolta</member>

<member>Sigma/Foveon</member>

<member>AGFA</member>

<member>Kyocera</member>

<member>Ricoh</member>

<member>Epson</member>

</simplelist>

</para>

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Пример использования функции <function>exif_read_data</function></title>

<programlisting role="php">

<![CDATA[

<?php

echo "test1.jpg:<br />\n";

$exif = exif_read_data('tests/test1.jpg', 'IFD0');

echo $exif===false ? "Функция не нашла данные заголовка.<br />\n" : "Изображение содержит заголовки<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>

Первый вызов завершается неудачей, поскольку заголовки

изображения не содержат информации.

</para>

&example.outputs.similar;

<screen role="php">

<![CDATA[

test1.jpg:

Функция не нашла данные заголовка.

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> с потоковым ресурсом (доступно с PHP 7.2.0)

</title>

<programlisting role="php">

<![CDATA[

<?php

// Открываем файл в бинарном режиме

$fp = fopen('/path/to/image.jpg', 'rb');

if (!$fp) {

echo 'Ошибка: Невозможно открыть файл для чтения';

exit;

}

// Попытка прочитать заголовки exif

$headers = exif_read_data($fp);

if (!$headers) {

echo 'Ошибка: невозможно прочитать заголовки exif';

exit;

}

// Напечатать заголовки 'COMPUTED'

echo 'Заголовки EXIF:' . 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>

Если модуль <link linkend="ref.mbstring">mbstring</link> включили, то exif будет пытаться

обрабатывать Юникод и брать кодировку как указано в

параметрах конфигурации <link linkend="ini.exif.decode-unicode-motorola">exif.decode_unicode_motorola</link>

и <link linkend="ini.exif.decode-unicode-intel">exif.decode_unicode_intel</link>.

Модуль exif не будет пытаться определить кодировку сам, правильную кодировку

для декодирования указывает пользователь путём установки одной из

двух INI-директив перед вызовом функции <function>exif_read_data</function>.

</para>

</note>

<note>

<para>

Если параметр <parameter>file</parameter> указали для передачи в функцию

потока, поток должен быть перематываемым. Обратите внимание, что файловый

позиционный указатель не изменится после завершения работы функции.

</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

-->