archived-doc-ru/reference/session/upload-progress.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 184f3f7bd45643cb80f828d0bb001991ec3a5fad Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<chapter xml:id="session.upload-progress" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Отслеживание хода загрузки файлов через сессии</title>

 <para>
  PHP умеет отслеживать ход загрузки отдельных файлов, если включить
  INI-директиву <link linkend="ini.session.upload-progress.enabled">session.upload_progress.enabled</link>.
  Эта информация не приносит пользы самому запросу на отправку файла,
  но во время загрузки файла приложение может отправить POST-запрос отдельной конечной точке, например
  через интерфейс <acronym>XHR</acronym>, чтобы проверить статус.
 </para>
 <para>
  Ход загрузки будет доступен в суперглобальной переменной
  <varname>$_SESSION</varname> по мере загрузки файла,
  и при отправке POST-переменной с тем же именем, которое установили для INI-параметра
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>.
  Когда PHP обнаруживает такие POST-запросы, он заполняет
  в переменной <varname>$_SESSION</varname> массив, в котором ключом будет конкатенация
  значений опций
  <link linkend="ini.session.upload-progress.prefix">session.upload_progress.prefix</link>
  и
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>.
  Ключ обычно получают путём чтения значений этих директив, то есть:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php

$key = ini_get("session.upload_progress.prefix") . $_POST[ini_get("session.upload_progress.name")];
var_dump($_SESSION[$key]);

?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  Разработчики <emphasis>отменяют</emphasis> текущую загрузку файла через установку
  для ключа <literal>$_SESSION[$key]["cancel_upload"]</literal> значения &true;, когда требуется.
  При загрузке набора файлов в одном запросе этот способ отменит
  только текущую загрузку файла, которая уже началась, и загрузки в очереди,
  но не удалит загрузки, которые уже завершились.
  При отмене загрузки таким способом PHP установит элементу массива
  <varname>$_FILES</varname> с ключом <literal>error</literal>
  значение константы <constant>UPLOAD_ERR_EXTENSION</constant>.
 </para>
 <para>
  Директивы <link linkend="ini.session.upload-progress.freq">session.upload_progress.freq</link>
  и <link linkend="ini.session.upload-progress.min-freq">session.upload_progress.min_freq</link>
  определяют, как часто требуется обновлять информацию о ходе загрузки.
  Накладные расходы на эту функцию не ощущаются при разумных значениях этих настроек.
 </para>
 <para>
  <example>
   <title>Пример информации</title>
   <para>
    Пример структуры массива прогресса загрузки.
   </para>
   <programlisting role="html" xml:id="session.upload-progress.example-form">
<![CDATA[
<form action="upload.php" method="POST" enctype="multipart/form-data">
    <input type="hidden" name="<?php echo ini_get("session.upload_progress.name"); ?>" value="123" />
    <input type="file" name="file1" />
    <input type="file" name="file2" />
    <input type="submit" />
</form>
]]>
   </programlisting>
   <para>
    Данные, которых хранятся в сессии, будут выглядеть вот так:
   </para>
   <programlisting role="php" xml:id="session.upload-progress.example-array">
<![CDATA[
<?php

<?php

$_SESSION["upload_progress_123"] = array(
    "start_time" => 1234567890,   // Время начала запроса
    "content_length" => 57343257, // Длина содержимого POST-запроса
    "bytes_processed" => 453489,  // Количество байтов, которые получил и обработал запрос
    "done" => false,              // После завершения обработки POST-запроса значение изменится на true,
                                  // независимо от того, успешно или нет завершилась обработка
    "files" => array(
        0 => array(
            "field_name" => "file1",       // Значение атрибута name поля <input/>
            // Следующие 3 элемента соответствуют элементам суперглобального массива $_FILES
            "name" => "foo.avi",
            "tmp_name" => "/tmp/phpxxxxxx",
            "error" => 0,
            "done" => true,                // Элемент получает значение true, когда обработчик POST-запроса
                                           // закончил обработку файла
            "start_time" => 1234567890,    // Время начала обработки файла
            "bytes_processed" => 57343250, // Количество байтов, которые запрос получил и обработал для файла
        ),
        // Ещё один файл, загрузка которого ещё не закончилась в том же запросе
        1 => array(
            "field_name" => "file2",
            "name" => "bar.avi",
            "tmp_name" => NULL,
            "error" => 0,
            "done" => false,
            "start_time" => 1234567899,
            "bytes_processed" => 54554,
        ),
    )
);

?>
]]>
   </programlisting>
  </example>
 </para>
 <warning>
  <para>
   Для правильной работы требуется отключить буферизацию запросов веб-сервера,
   иначе PHP увидит загрузку файла только после полной загрузки.
   Серверы наподобие Nginx буферизуют большие запросы.
  </para>
 </warning>
 <caution>
  <para>
   Информация о ходе загрузки записывается в сессию перед выполнением
   скриптов. Поэтому PHP начнёт сессию без информации о ходе загрузки,
   если изменить название сессии функцией
   <function>ini_set</function> или <function>session_name</function>.
  </para>
 </caution>
</chapter>
<!-- 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
-->