archived-doc-ru/reference/exif/functions/exif-read-data.xml

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