<?xml version="1.0" encoding="utf-8"?>

<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">

</programlisting>

&example.outputs;

<screen>

</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>