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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 184f3f7bd45643cb80f828d0bb001991ec3a5fad Maintainer: yannick 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>Progression d'un téléversement (upload) en session</title>

 <para>
  Lorsque l'option de configuration
  <link linkend="ini.session.upload-progress.enabled">session.upload_progress.enabled</link>
  est active, PHP sera capable de traquer la progression d'un fichier en
  cours de téléversement (upload). Cette information n'est pas particulièrement utile
  pour la requête de téléversement en tant que tel, mais pendant le téléversement,
  une application peut envoyer une requête POST séparée (via 
  <acronym>XHR</acronym> par exemple) pour vérifier le statut de ce téléversement.
 </para>
 <para>
  La progression du téléversement sera disponible dans la variable super-globale
  <varname>$_SESSION</varname> lorsque le téléversement est en cours,
  et lors d'un envoi en méthode POST d'une variable du même nom que celui
  défini dans l'option de configuration INI
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>.
  Lorsque PHP détecte une requête POST de ce type, il remplira un tableau dans
  <varname>$_SESSION</varname>, où l'index est une valeur concaténée des options
  de configuration
  <link linkend="ini.session.upload-progress.prefix">session.upload_progress.prefix</link>
  et
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>.
  La clé est typiquement récupérée en lisant ces configurations INI, c.-à-d.
  <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>
  Il est également possible d'<emphasis>annuler</emphasis> le téléversement courant
  en définissant la clé <literal>$_SESSION[$key]["cancel_upload"]</literal> à la valeur
  &true;. Lors du téléversement de plusieurs fichiers dans la même
  requête, cette action n'annulera que le fichier actuellement en cours de téléchargement,
  ainsi que ceux en attente de téléversement mais n'annulera pas les téléversements
  terminés avec succès. Lorsqu'un téléversement est annulé en utilisant cette méthode,
  la clé <literal>error</literal> du tableau <varname>$_FILES</varname> sera définie à
  <constant>UPLOAD_ERR_EXTENSION</constant>.
 </para>
 <para>
  Les options de configuration INI
  <link linkend="ini.session.upload-progress.freq">session.upload_progress.freq</link>
  et
  <link linkend="ini.session.upload-progress.min-freq">session.upload_progress.min_freq</link>
  contrôlent la fréquence de mise à jour des informations de progression de téléversement.
  Avec une configuration raisonnable de ces 2 options, le surcoût en terme
  de charge est quasi nul.
 </para>
 <para>
  <example>
   <title>Exemple</title>
   <para>
    Exemple de structure du tableau contenant les informations de
    téléversement.
   </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>
    Les données stockées en session ressembleront à :
   </para>
   <programlisting role="php" xml:id="session.upload-progress.example-array">
<![CDATA[
<?php
$_SESSION["upload_progress_123"] = array(
 "start_time" => 1234567890,   // L'heure de la requête
 "content_length" => 57343257, // Longueur du contenu POST
 "bytes_processed" => 453489,  // Quantité d'octets reçus et traités
 "done" => false,              // true lorsque le gestionnaire POST a terminé, avec succès ou non
 "files" => array(
  0 => array(
   "field_name" => "file1",       // Nom du champ <input/>
   // Les 3 éléments suivants sont équivalents à ceux dans $_FILES
   "name" => "foo.avi",
   "tmp_name" => "/tmp/phpxxxxxx",
   "error" => 0,
   "done" => true,                // True lorsque le gestionnaire POST a terminé de gérer ce fichier
   "start_time" => 1234567890,    // L'heure de début de requête
   "bytes_processed" => 57343250, // Quantité d'octets reçus et traités pour ce fichier
  ),
  // Un autre fichier, en cours de téléversement, dans la même requête
  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>
   La mise en mémoire tampon de la requête du serveur web doit être désactivée
   pour la bonne marche de cette fonctionnalité, sinon PHP ne verra le fichier
   qu'une fois qu'il sera totalement téléversé. Les serveurs tels que Nginx
   sont connus pour mettre en mémoire tampon des grosses requêtes.
  </para>
 </warning>
 <caution>
  <para>
   Les informations de la progression du téléversement sont écrites en session avant
   qu'un script soit exécuté. Par conséquent, changer le nom de session grâce à
   <function>ini_set</function> ou <function>session_name</function> donnera une
   session sans les informations de progression du téléversement.
  </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
-->