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

<refentry xml:id="function.extract" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>extract</refname>

<refpurpose>Переводит элементы массива в переменные текущей таблицы символов</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>

Функция импортирует переменные в текущую <link linkend="features.gc.refcounting-basics">таблицу символов</link>

на основе элементов массива.

</para>

<para>

Функция проверяет каждый ключ на соответствие правилам именования переменных

и обрабатывает конфликты имён с переменными текущей таблицы символов.

</para>

<warning>

<para>

Функцией <function>extract</function> опасно извлекать переменные из ненадёжных данных

наподобие суперглобальных переменных <varname>$_GET</varname> или <varname>$_FILES</varname>, которые содержат пользовательский ввод.

</para>

</warning>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>array</parameter></term>

<listitem>

<para>

Ассоциативный массив. Функция интерпретирует ключи массива

как названия переменных, а значения элементов — как значения переменных.

На основе каждой пары «ключ — значение» функция создаст

или обновит переменную в текущей таблице символов

с учётом значений параметров <parameter>flags</parameter> и <parameter>prefix</parameter>.

</para>

<para>

Функция ожидает ассоциативный массив; импорт переменных на основе элементов индексного массива

выполняется только при передаче флага <constant>EXTR_PREFIX_ALL</constant>

или <constant>EXTR_PREFIX_INVALID</constant>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>flags</parameter></term>

<listitem>

<para>

Параметр <parameter>flags</parameter> определяет способ

обработки недопустимых или числовых ключей и коллизий. Параметр

принимает следующие значения:

<variablelist>

<varlistentry>

<term><constant>EXTR_OVERWRITE</constant></term>

<listitem>

<simpara>

При коллизии перезаписывать переменную в текущей таблице символов.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>EXTR_SKIP</constant></term>

<listitem>

<simpara>

При коллизии не перезаписывать переменную в текущей таблице символов.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>EXTR_PREFIX_SAME</constant></term>

<listitem>

<simpara>

При коллизии добавлять к названию

переменной префикс

<parameter>prefix</parameter>.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>EXTR_PREFIX_ALL</constant></term>

<listitem>

<simpara>

Добавлять префикс <parameter>prefix</parameter> к названию каждой переменной.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>EXTR_PREFIX_INVALID</constant></term>

<listitem>

<simpara>

Добавлять префикс <parameter>prefix</parameter>

только к недопустимым или числовым названиям переменных.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>EXTR_IF_EXISTS</constant></term>

<listitem>

<simpara>

Не создавать новые переменные, а только перезаписывать в текущей таблице символов.

Флаг полезен для определения «белого списка»

переменных, чтобы затем извлечь только предопределённые переменные, например,

из суперглобального массива <varname>$_REQUEST</varname>.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>EXTR_PREFIX_IF_EXISTS</constant></term>

<listitem>

<simpara>

Создать только префикс-версии переменных,

если переменная без префикса уже содержится в текущей таблице символов.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>EXTR_REFS</constant></term>

<listitem>

<simpara>

Извлечь переменные как ссылки:

переменные импортируются как ссылки

на значения элементов массива <parameter>array</parameter>.

Флаг работает отдельно или в комбинации с другими флагами

параметра <parameter>flags</parameter> при объединении через побитовое ИЛИ.

</simpara>

</listitem>

</varlistentry>

</variablelist>

</para>

<para>

Значение параметра <parameter>flags</parameter>

по умолчанию равно <constant>EXTR_OVERWRITE</constant>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>prefix</parameter></term>

<listitem>

<para>

Обратите внимание, параметр <parameter>prefix</parameter>

обязателен только при установке для параметра <parameter>flags</parameter>

флагов <constant>EXTR_PREFIX_SAME</constant>,

<constant>EXTR_PREFIX_ALL</constant>,

<constant>EXTR_PREFIX_INVALID</constant>

или <constant>EXTR_PREFIX_IF_EXISTS</constant>.

Переменная не импортируется в текущую таблицу символов,

если после добавления префикса создаётся

недопустимое название переменной. Между префиксом и ключом массива

автоматически вставляется символ подчёркивания: prefix_key.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Функция возвращает количество переменных, затронутых в таблице символов.

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Пример импорта переменных функцией <function>extract</function></title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

<para>

Переменная <varname>$size</varname> не перезаписалась

из-за установки флага <constant>EXTR_PREFIX_SAME</constant>,

поэтому функция создала переменную <varname>$wddx_size</varname>.

При установке флага <constant>EXTR_SKIP</constant>

функция не создала бы переменную <varname>$wddx_size</varname>.

С флагом <constant>EXTR_OVERWRITE</constant>

переменная <varname>$size</varname> получила бы

значение "medium", а при установке флага <constant>EXTR_PREFIX_ALL</constant>

функция создала бы

переменные <varname>$wddx_color</varname>,

<varname>$wddx_size</varname> и <varname>$wddx_shape</varname>.

</para>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<warning>

<para>

Функцией <function>extract</function> опасно извлекать переменные из ненадёжных данных

наподобие суперглобальных переменных <varname>$_GET</varname> или <varname>$_FILES</varname>, которые содержат пользовательский ввод.

При вынужденном извлечении ненадёжных данных в параметр <parameter>flags</parameter>

передают константу <constant>EXTR_SKIP</constant> или другой флаг, который запрещает перезапись текущих значений,

и извлекают переменные с учётом порядка значений

в директиве <link linkend="ini.variables-order">variables_order</link>

файла <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>