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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<!-- EN-Revision: 1.18 Maintainer: didou Status: ready -->
 <refentry id="function.extract">
  <refnamediv>
   <refname>extract</refname>
   <refpurpose>
    Importe les variables dans la table des symboles
   </refpurpose>
  </refnamediv>
  <refsect1>
   &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></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>prefix</parameter></methodparam>
   </methodsynopsis>
   <para>
    <function>extract</function> sert à exporter un tableau vers
    la table des symboles. Elle prend un tableau associatif
    <parameter>var_array</parameter>, 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>
   <note>
    <para>
     Depuis la version 4.0.5, <function>extract</function> retourne le nombre de
     variables extraites.
    </para>
   </note>
    <note>
     <para>
      <constant>EXTR_IF_EXISTS</constant> et <constant>EXTR_PREFIX_IF_EXISTS</constant>
      ont été introduites en &php; version 4.2.0.
     </para>
    </note>
    <note>
     <para>
      <constant>EXTR_REFS</constant> a été introduite en &php; 4.3.0.
     </para>
    </note>
   <para>
    <function>extract</function> vérifie l'existence de la variable avant
    de la créer. 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.
      A partir de la version 4.0.5, les variables numériques sont aussi préfixées.
     </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>. Ceci a
      été ajouté en &php; 4.0.5.
     </simpara>
    </listitem>
    </varlistentry>
     <varlistentry>
       <term><constant>EXTR_IF_EXISTS</constant></term>
       <listitem>
        <simpara>
         Ecrase 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
         d'extraire du tableau les valeurs que vous avez déjà définies
         grâce à <varname>$_REQUEST</varname>, par exemple.
         Cette option a été ajoutée en &php; 4.2.0.
        </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.
         Cette option a été ajoutée en &php; 4.2.0.
        </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 option avec
         l'opérateur OR, dans le paramètre <parameter>extract_type</parameter>.
         Cette option a été ajoutée en &php; 4.3.0.
        </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>
   <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.
   </para>
   <para>
    <function>extract</function> retourne le nombre de variables réellement
    importées dans la table des symboles.
   </para>
   <warning>
    <para>
     N'utilisez pas <function>extract</function> sur des données inconnues, comme
     les données utilisateurs (<varname>$_GET</varname>, etc).
     Si vous le faites, par exemple, pour rendre compatible un vieux code avec
     <link linkend="security.registerglobals">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 <varname>$_SERVER</varname>, <varname>$_SESSION</varname>,
     <varname>$_COOKIE</varname>, <varname>$_POST</varname> et
     <varname>$_GET</varname> dans cet ordre.
    </para>
   </warning>
   <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>
   <para>
    <example>
     <title>Exemple avec <function>extract</function></title>
     <programlisting role="php">
<![CDATA[
<?php
// Supposons que $var_array est un tableau retourné
// par wddx_deserialize()
$taille = "grand";
$var_array = array("couleur" => "bleu",
                   "taille"  => "moyen",
                   "forme"   => "sphere");
extract($var_array, EXTR_PREFIX_SAME, "wddx");
echo "$couleur, $taille, $forme, $wddx_taille\n";
?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
bleu, grand, sphere, moyen
]]>
     </screen>
    </example>
   </para>
   <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>
   <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>
   <para>
    Voir aussi <function>compact</function>.
   </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:"../../../../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
-->