doc-fr/features/file-upload.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: fc174e8d6162091550edde46159917ee7e5a2e73 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<chapter xml:id="features.file-upload" xmlns="http://docbook.org/ns/docbook">
 <title>Gestion des chargements de fichiers</title>
 
 <sect1 xml:id="features.file-upload.post-method">
  <title>Chargements de fichiers par méthode POST </title>
  
  <simpara>
   Cette fonctionnalité permet aux personnes de télécharger à la fois du texte
   et des fichiers binaires. Avec les fonctions d'identification et de
   manipulation de fichiers de PHP, vous avez le contrôle total pour définir
   qui a le droit de télécharger, mais aussi ce qui sera fait du fichier une
   fois qu'il sera téléchargé.
  </simpara>
  <simpara>
   PHP est capable de recevoir des fichiers émis par
   un navigateur conforme à la norme RFC-1867.
  </simpara>
  
  <note>
   <title>Notes de configuration</title>
   <para>
    Voir aussi les directives
    <link linkend="ini.file-uploads">file_uploads</link>,
    <link linkend="ini.upload-max-filesize">upload_max_filesize</link>,
    <link linkend="ini.upload-tmp-dir">upload_tmp_dir</link>,
    <link linkend="ini.post-max-size">post_max_size</link> et
    <link linkend="ini.max-input-time">max_input_time</link> dans &php.ini;
   </para>
  </note>
  
  <para>
   PHP supporte aussi le chargement par la méthode PUT comme dans le
   navigateur <productname>Netscape Composer</productname>
   et <productname>Amaya</productname> du W3C. Reportez-vous au chapitre sur le
   <link linkend="features.file-upload.put-method">support de la
    méthode PUT</link>.
  </para>
  
  <para>
   <example>
    <title>Formulaire de chargement de fichier</title>
    <para>
     Un formulaire de téléchargement de fichiers peut être construit
     en créant un formulaire spécifique comme ceci :
    </para>
    <programlisting role="html">
<![CDATA[
<!-- Le type d'encodage des données, enctype, DOIT être spécifié comme ce qui suit -->
<form enctype="multipart/form-data" action="_URL_" method="post">
  <!-- MAX_FILE_SIZE doit précéder le champ input de type file -->
  <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
  <!-- Le nom de l'élément input détermine le nom dans le tableau $_FILES -->
  Envoyez ce fichier : <input name="userfile" type="file" />
  <input type="submit" value="Envoyer le fichier" />
</form>
]]>
    </programlisting>
    <para>
     <literal>_URL_</literal> dans l'exemple précédent doit être remplacé et
     pointé vers un fichier PHP.
    </para>
    <para>
     Le champ caché <literal>MAX_FILE_SIZE</literal> (mesuré en octets) doit
     précéder le champ input de type file et sa valeur représente la taille
     maximale acceptée du fichier par PHP.
     Cet élément de formulaire doit toujours être utilisé, car il permet
     d'informer l'utilisateur que le transfert désiré est trop lourd
     avant d'atteindre la fin du téléchargement. Gardez à l'esprit que
     ce paramètre peut être "trompé" du côté du navigateur facilement, aussi
     ne faites pas confiance à ce dernier, ne s'agissant finalement que d'une
     fonctionnalité de convenance côté client. Le paramètre PHP (côté serveur)
     à propos de la taille maximale d'un fichier téléchargé,
     ne peut, lui, être trompé.
    </para>
   </example>
  </para>
  
  <note>
   <para>
    Assurez-vous que votre formulaire de téléchargement de fichier contienne
    <literal>enctype="multipart/form-data"</literal>, sinon,
    le fichier se sera pas téléchargé.
   </para>
  </note>
  
  <para>
   La variable globale <varname>$_FILES</varname> va contenir toutes les
   informations sur le fichier téléchargé. Son contenu est détaillé
   dans notre exemple ci-dessous. Notez que l'on suppose que le nom
   de la variable du fichier téléchargé est <emphasis>userfile</emphasis>, tel que
    défini dans le formulaire ci-dessus, mais peut être n'importe quel nom.
    <variablelist>
     <varlistentry>
      <term><varname>$_FILES['userfile']['name']</varname></term>
      <listitem>
       <para>
        Le nom original du fichier, tel que sur la machine du client web.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['type']</varname></term>
      <listitem>
       <para>
        Le type MIME du fichier, si le navigateur a fourni cette information.
        Par exemple, cela pourra être <literal>"image/gif"</literal>.
        Ce type mime n'est cependant pas vérifié du côté de PHP et, donc,
        ne prend pas sa valeur pour se synchroniser.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['size']</varname></term>
      <listitem>
       <para>
        La taille, en octets, du fichier téléchargé.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['tmp_name']</varname></term>
      <listitem>
       <para>
        Le nom temporaire du fichier qui sera chargé sur la machine serveur.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['error']</varname></term>
      <listitem>
       <para>
        Le <link linkend="features.file-upload.errors">code d'erreur</link>
        associé au téléchargement de fichier.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['full_path']</varname></term>
      <listitem>
       <para>
        Le chemin entier tel que soumit par le navigateur.
        Cette valeur ne contient pas toujours une vraie hiérarchie de dossier,
        et il ne faut pas lui faire confiance.
        Disponible à partir de PHP 8.1.0.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
  </para>
  <para>
   Le fichier téléchargé sera stocké temporairement dans le dossier
   temporaire du système, à moins qu'un autre dossier soit fourni avec
   la directive <link linkend="ini.upload-tmp-dir">upload_tmp_dir</link> du
   &php.ini;. Le dossier par défaut du serveur peut être changé
   dans l'environnement via la variable <envar>TMPDIR</envar>.
   Modifier la valeur de cette variable avec la fonction <function>putenv</function>
   dans un script PHP sera sans effet. Cette variable d'environnement
   peut aussi être utilisée pour s'assurer que d'autres opérations
   fonctionnent aussi sur les fichiers téléchargés.
   <example>
    <title>Validation de téléchargement de fichiers</title>
    <para>
     Voyez aussi les fonctions <function>is_uploaded_file</function> et
     <function>move_uploaded_file</function> pour plus d'informations.
     L'exemple suivant va télécharger un fichier venant d'un formulaire.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$uploaddir = '/var/www/uploads/';
$uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

echo '<pre>';
if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
    echo "Le fichier est valide, et a été téléchargé
           avec succès. Voici plus d'informations :\n";
} else {
    echo "Attaque potentielle par téléchargement de fichiers.
          Voici plus d'informations :\n";
}

echo 'Voici quelques informations de débogage :';
print_r($_FILES);

echo '</pre>';

?>
]]>
    </programlisting>
   </example>
  </para>
  <simpara>
   Le script PHP qui reçoit le fichier chargé doit pouvoir
   gérer le fichier de manière appropriée. Vous
   pouvez utiliser la variable <varname>$_FILES['userfile']['size']</varname> pour recaler
   tous les fichiers qui sont trop gros ou trop petits. Vous pouvez utiliser
   la variable <varname>$_FILES['userfile']['type']</varname> pour écarter
   les fichiers qui n'ont pas le bon type, mais l'utiliser uniquement pour une série de
   vérifications, car cette valeur est complètement sous le contrôle du client
   et n'est pas vérifiée du côté de PHP.
   Vous pouvez utiliser l'information dans
   <varname>$_FILES['userfile']['error']</varname> et adapter votre politique
   en fonction des <link linkend="features.file-upload.errors">codes d'erreur</link>.
   Quelle que soit votre politique, vous devriez soit effacer le fichier du
   dossier temporaire, soit le déplacer.
  </simpara>
  <simpara>
   Si aucun fichier n'est sélectionné dans le formulaire, PHP retournera
   &zero; dans <varname>$_FILES['userfile']['size']</varname>
   et rien du tout dans <varname>$_FILES['userfile']['tmp_name']</varname>.
  </simpara>
  <simpara>
   Le fichier sera automatiquement effacé du dossier temporaire
   à la fin du script, s'il n'a pas été déplacé ou renommé.
  </simpara>
  <example>
   <title>Envoi d'un tableau de fichiers</title>
   <para>
    PHP supporte les <link linkend="faq.html.arrays">tableaux en HTML</link>
    ainsi qu'avec les fichiers.
   </para>
   <programlisting role="html">
<![CDATA[
<form action="" method="post" enctype="multipart/form-data">
<p>Images:
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="submit" value="Send" />
</p>
</form>
]]>
   </programlisting>
   <programlisting role="php">
<![CDATA[
<?php
foreach ($_FILES["pictures"]["error"] as $key => $error) {
    if ($error == UPLOAD_ERR_OK) {
        $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
        // basename() peut empêcher les attaques "filesystem traversal";
        // une autre validation/nettoyage du nom de fichier peux être appropriée
        $name = basename($_FILES["pictures"]["name"][$key]);
        move_uploaded_file($tmp_name, "data/$name");
    }
}
?>
]]>
   </programlisting>
  </example>
  <para>
   La barre de progression de téléchargement peut être implémentée en utilisant <link
   linkend="session.upload-progress">la progression du chargement via les sessions</link>.
  </para>
 </sect1>
 
 <sect1 xml:id="features.file-upload.errors">
  <title>Explication sur les messages d'erreurs de chargement de fichiers</title>
  <simpara>
   PHP retourne un code d'erreur approprié dans le
   tableau de fichiers. Ce code d'erreur est accessible à l'index
   <literal>['error']</literal> du tableau, qui est créé durant
   le téléchargement par PHP. En d'autres termes, le message d'erreur
   est accessible dans la variable <varname>$_FILES['userfile']['error']</varname>.
  </simpara>
  <para>
   <variablelist>
    <varlistentry>
     <term><constant>UPLOAD_ERR_OK</constant></term>
     <listitem>
      <para>
       Valeur : 0. Aucune erreur, le téléchargement est correct.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><constant>UPLOAD_ERR_INI_SIZE</constant></term>
     <listitem>
      <para>
       Valeur : 1. La taille du fichier téléchargé excède la valeur de
       <link linkend="ini.upload-max-filesize">upload_max_filesize</link>,
       configurée dans le &php.ini;.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><constant>UPLOAD_ERR_FORM_SIZE</constant></term>
     <listitem>
      <para>
       Valeur : 2. La taille du fichier téléchargé excède la valeur de
       <emphasis>MAX_FILE_SIZE</emphasis>, qui a été spécifiée dans
       le formulaire HTML.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><constant>UPLOAD_ERR_PARTIAL</constant></term>
     <listitem>
      <para>
       Valeur : 3. Le fichier n'a été que partiellement téléchargé.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><constant>UPLOAD_ERR_NO_FILE</constant></term>
     <listitem>
      <para>
       Valeur : 4. Aucun fichier n'a été téléchargé.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><constant>UPLOAD_ERR_NO_TMP_DIR</constant></term>
     <listitem>
      <para>
       Valeur : 6. Un dossier temporaire est manquant.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><constant>UPLOAD_ERR_CANT_WRITE</constant></term>
     <listitem>
      <para>
       Valeur : 7. Échec de l'écriture du fichier sur le disque.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><constant>UPLOAD_ERR_EXTENSION</constant></term>
     <listitem>
      <para>
       Valeur : 8. Une extension PHP a arrêté l'envoi de fichier. PHP ne propose aucun
       moyen de déterminer quelle extension est en cause. L'examen du <function>phpinfo</function> peut aider.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </sect1>
 
 <sect1 xml:id="features.file-upload.common-pitfalls">
  <title>Erreurs classiques</title>
  <simpara>
   La variable <literal>MAX_FILE_SIZE</literal> ne peut pas spécifier une taille
   de fichier plus grande que la taille qui a été
   fixée par <link linkend="ini.upload-max-filesize">upload_max_filesize</link>,
   dans le &php.ini;. La valeur par défaut est 2 megaoctets.
  </simpara>
  <simpara>
   Si une limite de mémoire est activée, une plus grande valeur de
   <link linkend="ini.memory-limit">memory_limit</link> peut être nécessaire.
   Assurez-vous d'avoir défini une valeur pour
   <link linkend="ini.memory-limit">memory_limit</link> assez grande.
  </simpara>
  <simpara>
   Si la valeur de
   <link linkend="ini.max-execution-time">max_execution_time</link> est trop
   petite, le temps d'exécution du script peut excéder cette valeur.
   Assurez-vous d'avoir défini une valeur pour
   <literal>max_execution_time</literal> assez grande.
  </simpara>
  <note>
   <simpara>
    <link linkend="ini.max-execution-time">max_execution_time</link> affecte
    uniquement le temps d'exécution du script. Le temps passé sur l'activité
    qui apparaît en dehors de l'exécution du script comme les appels systèmes
    avec la fonction <function>system</function>, la fonction
    <function>sleep</function>, les requêtes sur les bases de données, le temps
    mis pour effectuer le téléchargement du fichier, etc. n'est pas inclus lors
    du calcul du temps maximal de l'exécution du script.
   </simpara>
  </note>
  <warning>
   <simpara>
    <link linkend="ini.max-input-time">max_input_time</link> définit le temps
    maximal, en secondes, au script pour recevoir les données ; cela inclut le
    téléchargement du fichier. Pour les fichiers multiples, ou les gros
    fichiers, ou encore pour les utilisateurs sur des connexions lentes,
    la valeur par défaut de <literal>60</literal> secondes peut être dépassée.
   </simpara>
  </warning>
  <simpara>
   Si <link linkend="ini.post-max-size">post_max_size</link> est défini de façon
   trop faible, les gros fichiers ne pourront pas être téléchargés. Assurez-vous
   de définir <literal>post_max_size</literal> avec une taille suffisante.
  </simpara>
  <simpara>
   La configuration de
   <link linkend="ini.max-file-uploads">max_file_uploads</link> contrôle le nombre
   maximum de fichiers qui peuvent être envoyés en une requête. Si le nombre de fichiers
   envoyés dépasse cette limite, alors <varname>$_FILES</varname> arrêtera la réception.
   Par exemple, si <link linkend="ini.max-file-uploads">max_file_uploads</link> vaut
   <literal>10</literal>, alors <varname>$_FILES</varname> ne contiendra jamais plus de
   10 entités.
  </simpara>
  <simpara>
   Ne pas valider les fichiers que vous manipulez peut donner l'accès
   aux utilisateurs à des fichiers sensibles dans d'autres dossiers !
  </simpara>
  <simpara>
   Du fait de la grande diversité des systèmes, nous ne pouvons garantir que les fichiers
   avec des noms exotiques (par exemple, ceux contenant des espaces) seront
   traités correctement.
  </simpara>
  <simpara>
   Le développeur ne doit pas mixer les champs <literal>input</literal>
   normaux et les champs de téléchargement dans une même variable 
   (en utilisant un nom d'<literal>input</literal> comme 
   <literal>foo[]</literal>).
  </simpara>
 </sect1>
 
 <sect1 xml:id="features.file-upload.multiple">
  <title>Télécharger plusieurs fichiers simultanément</title>
  <simpara>
   Le téléchargement de plusieurs fichiers est possible
   en utilisant des noms différents dans l'attribut
   <literal>name</literal> de la balise <literal>input</literal>.
  </simpara>
  <simpara>
   Il est aussi possible de télécharger plusieurs fichiers simultanément
   et d'obtenir les informations sous forme de tableau. Pour cela, vous
   devez utiliser la syntaxe de tableau dans les noms de balises
   HTML, comme vous l'avez fait avec les sélections multiples
   et les boîtes à cocher.
  </simpara>
  <para>
   <example>
    <title>Télécharger plusieurs fichiers simultanément</title>
    <programlisting role="html">
<![CDATA[
<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Envoyez plusieurs fichiers : <br />
  <input name="userfile[]" type="file" /><br />
  <input name="userfile[]" type="file" /><br />
  <input type="submit" value="Envoyer les fichiers" />
</form>
]]>
    </programlisting>
   </example>
  </para>
  <simpara>
   Lorsque le formulaire ci-dessus a été envoyé, les
   tableaux <varname>$_FILES['userfile']</varname>,
   <varname>$_FILES['userfile']['name']</varname>, et
   <varname>$_FILES['userfile']['size']</varname> seront initialisés.
  </simpara>
  <simpara>
   Par exemple, supposons que les fichiers
   <filename>/home/test/review.html</filename> et
   <filename>/home/test/xwp.out</filename> ont été téléchargés. Dans ce cas,
   <varname>$_FILES['userfile']['name'][0]</varname>
   contient <filename>review.html</filename> et
   <varname>$_FILES['userfile']['name'][1]</varname> contient
   <filename>xwp.out</filename>. Similairement,
   <varname>$_FILES['userfile']['size'][0]</varname> va contenir
   la taille du fichier <filename>review.html</filename>, etc.
  </simpara>
  <simpara>
   <varname>$_FILES['userfile']['name'][0]</varname>,
   <varname>$_FILES['userfile']['tmp_name'][0]</varname>,
   <varname>$_FILES['userfile']['size'][0]</varname> et
   <varname>$_FILES['userfile']['type'][0]</varname> sont aussi
   créées.
  </simpara>
  <warning>
   <simpara>
    Le paramètre
    <link linkend="ini.max-file-uploads">max_file_uploads</link> limite le nombre
    de fichiers qui peuvent être envoyés en une requête. Vous devrez vérifier que
    votre formulaire ne tente pas d'envoyer plus de fichiers dans la requête que ne
    le tolère cette limite.
   </simpara>
  </warning>
  <para>
   <example>
    <title>Téléverser un dossier entier</title>
    <simpara>
     Dans les champs de téléversement de fichier HTML, il est possible de
     téléverser un dossier entier avec l'attribut <literal>webkitdirectory</literal>.
     Cette fonctionnalité est supportée dans la plupart des navigateurs modernes.
    </simpara>
    <simpara>
     Avec l'information <literal>full_path</literal>, il est possible de
     stocker les chemins relatifs ou reconstruire la même hiérarchie de dossier sur le dossier.
    </simpara>
    <programlisting role="html">
<![CDATA[
<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Send this directory:<br />
  <input name="userfile[]" type="file" webkitdirectory multiple />
  <input type="submit" value="Send files" />
</form>
]]>
    </programlisting>
   </example>
   <warning>
    <simpara>
     L'attribut <literal>webkitdirectory</literal> n'est pas standard et n'est
     pas actuellement en cours de standardisation.
     Ceci n'est pas à utiliser sur des sites de production tournés vers le Web :
     ça ne fonctionnera pas pour tous les utilisateurs.
     Il peut y avoir de grandes incompatibilités parmi les implémentations
     et le comportement peut changer dans le futur.
    </simpara>
    <simpara>
     PHP analyse uniquement les informations des chemins relatifs soumit par
     le navigateur/user-agent et transmet les informations dans le tableau
     <varname>$_FILES</varname>.
     Il n'y a aucune garanties que les valeurs dans le tableau
     <literal>full_path</literal> contienne une vraie structure de dossier
     et l'application PHP ne doit pas faire confiance à cette information.
    </simpara>
   </warning>
  </para>
 </sect1>
 
 <sect1 xml:id="features.file-upload.put-method">
  <title>Chargement par méthode PUT </title>
  <para>
   PHP supporte la méthode HTTP PUT utilisée par
   les navigateurs pour y stocker des fichiers sur un serveur.
   Les requêtes de type PUT sont beaucoup plus simples que
   les chargements de fichiers en utilisant le type POST, et elles
   ressemblent à :
   <example>
    <title>Méthode PUT pour les chargements de fichiers</title>
    <programlisting role="HTTP">
<![CDATA[
PUT /path/filename.html HTTP/1.1
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Normalement, cela signifie que le serveur distant va sauver
   les données qui suivent dans le fichier : <filename>/path/filename.html</filename>
   de son disque. Ce n'est évidemment pas très
   sécurisé de laisser Apache ou PHP écraser n'importe
   quel fichier de l'arborescence. Pour éviter ceci, il faut d'abord
   dire au serveur que vous voulez qu'un script PHP donné gère
   la requête. Avec Apache, il y a une directive pour cela :
   <emphasis>Script</emphasis>. Elle peut être placée
   n'importe où dans le fichier de configuration d'Apache.
   En général, les webmestres la placent dans le bloc
   <literal>&lt;Directory&gt;</literal>, ou peut-être dans le bloc
   <literal>&lt;VirtualHost&gt;</literal>.
   La ligne suivante fera très bien l'affaire :
   <example>
    <title>Directive Apache pour le chargement par méthode PUT</title>
    <programlisting>
<![CDATA[
Script PUT /put.php
]]>
    </programlisting>
   </example>
  </para>
  <simpara>
   Elle indique à Apache qu'il doit envoyer les requêtes
   de chargement par méthode PUT au script
   <filename>put.php</filename>. Bien entendu,
   cela présuppose que vous avez activé PHP pour qu'il
   prenne en charge les fichiers de type <filename>.php</filename>,
   et que PHP est actif. La ressource de destination pour toutes les
   requêtes PUT de ce script doit être le script lui-même, et non le
   nom du fichier que le fichier téléchargé doit avoir.
  </simpara>
  <simpara>
   Avec PHP, vous voudriez faire quelque chose comme ce qui suit
   dans votre put.php. Ceci va copier le contenu
   du fichier téléchargé dans le fichier 
   <filename>myputfile.ext</filename> sur le serveur.
   Vous devez probablement vouloir effectuer quelques vérifications et/ou
   identifier l'utilisateur avant d'effectuer cette copie de fichier.
  </simpara>
  <para>
   <example>
    <title>Sauvegarde de fichiers HTTP PUT</title>
    <programlisting role="php">
<![CDATA[
<?php
/* Les données PUT arrivent du flux */
$putdata = fopen("php://input", "r");

/* Ouvre un fichier pour écriture */
$fp = fopen("myputfile.ext", "w");

/* Lecture des données, 1 Ko à la fois et écriture dans le fichier */
while ($data = fread($putdata, 1024))
fwrite($fp, $data);

/* Fermeture du flux */
fclose($fp);
fclose($putdata);
?>
]]>
    </programlisting>
   </example>
  </para>
 </sect1>

  <sect1 xml:id="features.file-upload.errors.seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="security.filesystem">Sécurité des fichiers</link></member>
   </simplelist>
  </para>
 </sect1>
 
</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:
-->