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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f53ab502a11a52e82baca372c37d64e3f298b17c Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<!-- CREDITS: DavidA. -->
<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 role="reference">array</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>EXTR_OVERWRITE</constant></initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>prefix</parameter><initializer>""</initializer></methodparam>
  </methodsynopsis>
  <para>
   Importe les variables dans la
   <link linkend="features.gc.refcounting-basics">table des symboles</link>.
  </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>
  <warning>
   <para>
    N'utiliser pas <function>extract</function> sur des données non sûres comme les entrées utilisateur
    (ex. <varname>$_GET</varname>, <varname>$_FILES</varname>).
   </para>
  </warning>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>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>flags</parameter>
       et <parameter>prefix</parameter>.
      </para>
      <para>
       Il faut utiliser un tableau associatif. Un tableau indexé numériquement
       ne produira aucun résultat, à moins que l'on n'utilise l'option
       <constant>EXTR_PREFIX_ALL</constant> ou <constant>EXTR_PREFIX_INVALID</constant>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Le traitement des collisions est
       déterminé par <parameter>flags</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 qu'on a 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>array</parameter>. Il est possible d'utiliser cette
           option seule, ou bien la combiner avec d'autres options avec
           l'opérateur OR, dans le paramètre <parameter>flags</parameter>.
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       Si <parameter>flags</parameter> est omis, <function>extract</function>
       utilisera <constant>EXTR_OVERWRITE</constant> par défaut.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>prefix</parameter></term>
     <listitem>
      <para>
       Il est à noter que <parameter>prefix</parameter> n'est nécessaire que pour
       les valeurs de <parameter>flags</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="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>extract</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$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>$size</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_size</varname>. Si
     <constant>EXTR_SKIP</constant> avait été utilisée, alors
     <varname>$wddx_size</varname> n'aurait pas été créé.
     Avec <constant>EXTR_OVERWRITE</constant>, <varname>$size</varname>
     aurait pris la valeur "medium", et avec <constant>EXTR_PREFIX_ALL</constant>,
     les variables créées seraient <varname>$wddx_color</varname>,
     <varname>$wddx_size</varname> et <varname>$wddx_shape</varname>.
    </para>
   </example>
  </para>
 </refsect1>
 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    N'utiliser pas <function>extract</function> sur des données inconnues, comme
    les données utilisateurs (c.-à-d. <varname>$_GET</varname>,
    <varname>$_FILES</varname>, etc.).
    Si on le fait, il faut s'assurer d'utiliser l'une des constantes
    <parameter>flags</parameter> qui n'écrasent pas les valeurs, comme
    <constant>EXTR_SKIP</constant>. Il est aussi à noter qu'il faut 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>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>compact</function></member>
    <member><function>list</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
-->