extract.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 4a7ddddc27271967b616ad3400cfbe2a9b48212b 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 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>
  <warning>
   <para>
    N'utilisez 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>
       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>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 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>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>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>
       Notez 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>
    <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>$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'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, assurez-vous d'utiliser l'une des constantes
    <parameter>flags</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>
 </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
-->