php-doc-en/reference/session/upload-progress.xml

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

<chapter xml:id="session.upload-progress" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Session Upload Progress</title>

 <para>
  When the
  <link linkend="ini.session.upload-progress.enabled">session.upload_progress.enabled</link>
  INI option is enabled, PHP will be able to track the upload progress of
  individual files being uploaded.
  This information isn't particularly useful for the actual upload request
  itself, but during the file upload an application can send a POST request
  to a separate endpoint (via <acronym>XHR</acronym> for example) to check the
  status.
 </para>
 <para>
  The upload progress will be available in the <varname>$_SESSION</varname>
  superglobal when an upload is in progress, and when POSTing a variable of
  the same name as the
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>
  INI setting is set to.
  When PHP detects such POST requests, it will populate an array in the
  <varname>$_SESSION</varname>, where the index is a concatenated value of the
  <link linkend="ini.session.upload-progress.prefix">session.upload_progress.prefix</link>
  and
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>
  INI options.
  The key is typically retrieved by reading these INI settings, i.e.
  <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>
  It is also possible to <emphasis>cancel</emphasis> the currently in-progress file
  upload, by setting the <literal>$_SESSION[$key]["cancel_upload"]</literal> key to
  &true;.
  When uploading multiple files in the same request, this will only cancel the
  currently in-progress file upload, and pending file uploads, but will not
  remove successfully completed uploads.
  When an upload is cancelled like this, the <literal>error</literal> key in
  <varname>$_FILES</varname> array will be set to
  <constant>UPLOAD_ERR_EXTENSION</constant>.
 </para>
 <para>
  The
  <link linkend="ini.session.upload-progress.freq">session.upload_progress.freq</link>
  and
  <link linkend="ini.session.upload-progress.min-freq">session.upload_progress.min_freq</link>
  INI options control how frequent the upload progress information should be
  recalculated.
  With a reasonable amount for these two settings, the overhead of this
  feature is almost non-existent.
 </para>
 <para>
  <example>
   <title>Example information</title>
   <para>
    Example of the structure of the progress upload array.
   </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>
    The data stored in the session will look like this:
   </para>
   <programlisting role="php" xml:id="session.upload-progress.example-array">
<![CDATA[
<?php
$_SESSION["upload_progress_123"] = array(
 "start_time" => 1234567890,   // The request time
 "content_length" => 57343257, // POST content length
 "bytes_processed" => 453489,  // Amount of bytes received and processed
 "done" => false,              // true when the POST handler has finished, successfully or not
 "files" => array(
  0 => array(
   "field_name" => "file1",       // Name of the <input/> field
   // The following 3 elements equals those in $_FILES
   "name" => "foo.avi",
   "tmp_name" => "/tmp/phpxxxxxx",
   "error" => 0,
   "done" => true,                // True when the POST handler has finished handling this file
   "start_time" => 1234567890,    // When this file has started to be processed
   "bytes_processed" => 57343250, // Number of bytes received and processed for this file
  ),
  // An other file, not finished uploading, in the same request
  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>
   The web server's request buffering has to be disabled for this to work
   properly, else PHP may see the file upload only once fully uploaded. Servers
   such as Nginx are known to buffer larger requests.
  </para>
 </warning>
 <caution>
  <para>
   The upload progress information is written to the session before any scripts
   are executed. Therefore changing the session name via <function>ini_set</function>
   or <function>session_name</function> will give a session without the upload
   progress information.
  </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
-->