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

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

<refnamediv>

<refname>parse_str</refname>

<refpurpose>Разбирает строку как аргументы URL-адреса</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>void</type><methodname>parse_str</methodname>

<methodparam><type>string</type><parameter>string</parameter></methodparam>

<methodparam><type>array</type><parameter role="reference">result</parameter></methodparam>

</methodsynopsis>

<para>

Функция разбирает строку <parameter>string</parameter> как аргументы URL-адреса

и заполняет переменную <parameter>result</parameter> массивом, в котором ключами становятся названия, а значениями — значения аргументов.

При пропуске параметра <parameter>result</parameter> функция

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

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>string</parameter></term>

<listitem>

<para>

Строка в формате аргументов URL-адреса.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>result</parameter></term>

<listitem>

<para>

Переменная по ссылке. Функция заполнит переменную парами

«ключ — значение», которые извлечёт из строки <parameter>string</parameter>.

При пропуске параметра <parameter>result</parameter>

каждый ключ станет отдельной переменной в локальной области видимости.

</para>

<warning>

<para>

Начиная с PHP 7.2 вызов функции с одним аргументом <emphasis>УСТАРЕЛ</emphasis>;

разработчики языка <emphasis>НАСТОЯТЕЛЬНО</emphasis> рекомендуют вызывать функцию

с аргументом <parameter>result</parameter>.

С PHP 8.0.0 параметр <parameter>result</parameter> стал <emphasis>обязательным</emphasis>.

</para>

</warning>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

&return.void;

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.0.0</entry>

<entry>

Параметр <parameter>result</parameter> стал обязательным.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

Вызов функции <function>parse_str</function> без второго аргумента теперь

выдаёт ошибку уровня <constant>E_DEPRECATED</constant>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Пример разбора аргументов URL-адреса функцией <function>parse_str</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

Функция заменит пробелы и точки в названиях аргументов URL-адреса символами подчёркивания

прежде чем создать ключи массива или локальные переменные,

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

Эти же правила относятся к названиям ключей в массиве

<parameter>result</parameter> при вызове функции с двумя аргументами.

<example>

<title>Пример искажения названия аргумента функцией <function>parse_str</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

Директива <link linkend="ini.max-input-vars">max_input_vars</link> ограничивает количество входных переменных,

которое обработает функция <function>parse_str</function>.

Превышение предела выдаёт ошибку уровня <constant>E_WARNING</constant>,

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

Предустановленное значение директивы <link linkend="ini.max-input-vars">max_input_vars</link> — 1000.

</para>

</note>

<note>

<para>

Перед заполнением массива <parameter>result</parameter> функция

декодирует названия и значения аргументов URL-адреса по правилам функции <function>urldecode</function>.

Названия переменных, которые функция создаёт при пропуске второго аргумента, тоже декодируются.

</para>

</note>

<note>

<para>

Строку аргументов текущего запроса содержит элемент

<varname>$_SERVER['QUERY_STRING']</varname>.

Дополнительную информацию о переменных запроса содержит раздел

«<link linkend="language.variables.external">Переменные из внешних источников</link>».

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>parse_url</function></member>

<member><function>pathinfo</function></member>

<member><function>http_build_query</function></member>

<member><function>urldecode</function></member>

</simplelist>

</para>

</refsect1>

</refentry>