doc-fr/reference/array/functions/extract.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->

<refentry xml:id="function.extract" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>extract</refname>
  <refpurpose>Importe les variables dans la table des symboles</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>extract</methodname>
   <methodparam><type>array</type><parameter>var_array</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>extract_type</parameter><initializer>EXTR_OVERWRITE</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>prefix</parameter></methodparam>
  </methodsynopsis>
  <para>
   Importe les variables dans la table des symboles.
  </para>
  <para>
   <function>extract</function> vérifie chaque clé afin de contrôler si elle a un nom
   de variable valide. Elle vérifie également les collisions avec des variables
   existantes dans la table des symboles.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>var_array</parameter></term>
     <listitem>
      <para>
       Un tableau associatif. Cette fonction crée les variables dont les
       noms sont les index de ce tableau, et leur affecte la valeur associée.
       Pour chaque paire clé/valeur, <function>extract</function> crée
       une variable, avec les paramètres <parameter>extract_type</parameter>
       et <parameter>prefix</parameter>.
      </para>
      <para>
       Vous devez utiliser un tableau associatif. Un tableau indexé numériquement
       ne produira aucun résultat, à moins que vous n'utilisiez l'option
       <constant>EXTR_PREFIX_ALL</constant> ou <constant>EXTR_PREFIX_INVALID</constant>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>extract_type</parameter></term>
     <listitem>
      <para>
       Le traitement des collisions est
       déterminé par <parameter>extract_type</parameter>.
       Ce paramètre peut prendre une des valeurs suivantes :
       <variablelist>
        <varlistentry>
         <term><constant>EXTR_OVERWRITE</constant></term>
         <listitem>
          <simpara>
           Lors d'une collision, réécrire la variable existante.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>EXTR_SKIP</constant></term>
         <listitem>
          <simpara>
           Lors d'une collision, ne pas réécrire la variable existante.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>EXTR_PREFIX_SAME</constant></term>
         <listitem>
          <simpara>
           Lors d'une collision, ajouter le préfixe <parameter>prefix</parameter>,
           et créer une nouvelle variable.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>EXTR_PREFIX_ALL</constant></term>
         <listitem>
          <simpara>
           Ajouter le préfixe <parameter>prefix</parameter> pour toutes les variables.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>EXTR_PREFIX_INVALID</constant></term>
         <listitem>
          <simpara>
           Préfixer uniquement les variables aux noms invalides ou numériques
           avec le préfixe <parameter>prefix</parameter>.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>EXTR_IF_EXISTS</constant></term>
         <listitem>
          <simpara>
           Écrase la variable uniquement si elle existe déjà dans la
           table des symboles, et, sinon, ne rien faire. Ceci est
           pratique pour définir une liste de variables valides, puis
           extraire du tableau les valeurs que vous avez déjà définies
           grâce à <varname>$_REQUEST</varname>, par exemple.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>EXTR_PREFIX_IF_EXISTS</constant></term>
         <listitem>
          <simpara>
           Ne crée que des variables préfixées, si la version non préfixée
           de la même variable existe dans la table des symboles courante.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>EXTR_REFS</constant></term>
         <listitem>
          <simpara>
           Extrait les variables sous forme de références. Cela signifie que
           les valeurs des variables importées font toujours référence aux
           valeurs des variables d'origine dans le paramètre
           <parameter>var_array</parameter>. Vous pouvez utiliser cette
           option seule, ou bien la combiner avec d'autres options avec
           l'opérateur OR, dans le paramètre <parameter>extract_type</parameter>.
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       Si <parameter>extract_type</parameter> est omis, <function>extract</function>
       utilise <constant>EXTR_OVERWRITE</constant> par défaut.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>prefix</parameter></term>
     <listitem>
      <para>
       Notez que <parameter>prefix</parameter> n'est nécessaire que pour
       les valeurs de <parameter>extract_type</parameter> suivantes :
       <constant>EXTR_PREFIX_SAME</constant>, <constant>EXTR_PREFIX_ALL</constant>,
       <constant>EXTR_PREFIX_INVALID</constant> ou <constant>EXTR_PREFIX_IF_EXISTS</constant>.
       Si le résultat préfixé n'est pas un nom de variable valide,
       il ne sera pas importé dans la table des symboles. Les préfixes sont
       automatiquement séparés de l'index du tableau par un caractère de
       soulignement.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne le nombre de variables importées avec succès dans la table
   des symboles.
  </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>4.3.0</entry>
       <entry>
        <constant>EXTR_REFS</constant> a été ajouté.
       </entry>
      </row>
      <row>
       <entry>4.2.0</entry>
       <entry>
        <constant>EXTR_IF_EXISTS</constant> et <constant>EXTR_PREFIX_IF_EXISTS</constant>
        ont été ajoutés.
       </entry>
      </row>
      <row>
       <entry>4.0.5</entry>
       <entry>
        Cette fonction retourne maintenant le nombre de variables extraites.
        <constant>EXTR_PREFIX_INVALID</constant> a été ajouté.
        <constant>EXTR_PREFIX_ALL</constant> inclut également les variables numériques.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>extract</function></title>
    <para>
     Une utilisation possible de la fonction <function>extract</function> est l'exportation
     vers la table des symboles de tableaux de variables retournés
     par <function>wddx_deserialize</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php

/* Supposons que $var_array est un tableau retourné par
   wddx_deserialize */

$size = "large";
$var_array = array("color" => "blue",
                   "size"  => "medium",
                   "shape" => "sphere");
extract($var_array, EXTR_PREFIX_SAME, "wddx");

echo "$color, $size, $shape, $wddx_size\n";

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
blue, large, sphere, medium
]]>
    </screen>
    <para>
     La variable <varname>$taille</varname> n'a pas été réécrite, car on
     avait spécifié le paramètre <constant>EXTR_PREFIX_SAME</constant>,
     qui a permis la création de <varname>$wddx_taille</varname>. Si
     <constant>EXTR_SKIP</constant> avait été utilisée, alors
     <varname>$wddx_taille</varname> n'aurait pas été créé.
     Avec <constant>EXTR_OVERWRITE</constant>, <varname>$taille</varname>
     aurait pris la valeur "moyen", et avec <constant>EXTR_PREFIX_ALL</constant>,
     les variables créées seraient <varname>$wddx_couleur</varname>,
     <varname>$wddx_taille</varname> et <varname>$wddx_forme</varname>.
    </para>
   </example>
  </para>
 </refsect1>
 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    N'utilisez pas <function>extract</function> sur des données inconnues, comme
    les données utilisateurs (i.e. <varname>$_GET</varname>,
    <varname>$_FILES</varname>, etc.).
    Si vous le faites, par exemple, pour rendre compatible un vieux code avec
    <link linkend="security.globals">register_globals</link>
    à Off de façon temporaire, assurez-vous d'utiliser l'une des constantes
    <parameter>extract_type</parameter> qui n'écrasent pas les valeurs, comme
    <constant>EXTR_SKIP</constant>. Sachez aussi que vous devez maintenant
    extraire dans le même ordre que celui défini dans <link
    linkend="ini.variables-order">variables_order</link> du <link
    linkend="ini">&php.ini;</link>.
   </para>
  </warning>
  <note>
   <para>
    Si vous avez la directive
    <link linkend="security.globals">register_globals</link> d'activée
    et que vous utilisez la fonction <function>extract</function>
    sur les variables <varname>$_FILES</varname> et que vous spécifiez
    la constante <constant>EXTR_SKIP</constant>, vous pourriez être surpris
    du résultat.
   </para>
   <warning>
    <para>
     Cette façon de faire n'est pas recommandée et est uniquement documentée
     ici pour bien comprendre le comportement.
     L'utilisation de la directive
     <link linkend="security.globals">register_globals</link> est obsolète
     et appeler la fonction <function>extract</function> sur des données
     partagées comme les variables <varname>$_FILES</varname> est, comme mentionné
     ci-dessus, un risque potentiel pour la sécurité. Si vous rencontrez
     ce problème, cela signifie que vous avez écrit votre code de la mauvaise
     manière pour au moins 2 raisons.
    </para>
   </warning>
   <programlisting role="php">
<![CDATA[
<?php

/* Supposez que $testfile est le nom d'un champ de téléchargement de fichier
   et que register_globals est actif. */

var_dump($testfile);
extract($_FILES, EXTR_SKIP);
var_dump($testfile);
var_dump($testfile['tmp_name']);

?>
]]>
   </programlisting>
   <simpara>
    Vous vous attendez à voir quelque chose comme :
   </simpara>
   <screen>
<![CDATA[
string(14) "/tmp/phpgCCPX8"
array(5) {
  ["name"]=>
  string(10) "somefile.txt"
  ["type"]=>
  string(24) "application/octet-stream"
  ["tmp_name"]=>
  string(14) "/tmp/phpgCCPX8"
  ["error"]=>
  int(0)
  ["size"]=>
  int(4208)
}
string(14) "/tmp/phpgCCPX8"
]]>
   </screen>
   <simpara>
    Cependant, vous devriez plutôt voir quelque comme :
   </simpara>
   <screen>
<![CDATA[
string(14) "/tmp/phpgCCPX8"
string(14) "/tmp/phpgCCPX8"
string(1) "/"
]]>
   </screen>
   <para>
    Ceci est dû au fait que, depuis que la directive
    <link linkend="security.globals">register_globals</link> est ative,
    la variable <varname>$testfile</varname> existe déjà dans le scope global
    lorsque la fonction <function>extract</function> est appelée.
    Et vû que la constante <constant>EXTR_SKIP</constant> est spécifiée,
    la variable <varname>$testfile</varname> n'est pas écrasée avec le contenu
    du tableau <constant>$_FILES</constant>, aussi, la variable
    <varname>$testfile</varname> reste une &string;.
    Parceque les <link linkend="language.types.string.substr">chaînes de caractères
    peuvent être accédées en utilisant la synthaxe des tableaux</link>
    et que la &string; non-numérique <literal>tmp_name</literal> est interprétée
    comme <literal>0</literal>, PHP voit <varname>$testfile['tmp_name']</varname>
    comme <varname>$testfile[0]</varname>.
   </para>
  </note>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>compact</function></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
-->