<?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>Analyse une chaîne de caractères comme une chaîne de requête 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>

Analyse la chaîne de caractères <parameter>string</parameter> comme s'il

s'agissait des paramètres passés via l'URL. Toutes les variables

qu'elle y repère sont alors créées, avec leurs valeurs respectives (ou

dans le tableau si <parameter>result</parameter> est fourni).

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

La chaîne d'entrée.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Une variable passée par référence, qui sera définie comme un tableau

contenant les paires clé-valeur extraites de <parameter>string</parameter>.

Si le paramètre <parameter>result</parameter> n'est pas passé,

une variable séparée est définie dans la portée locale pour chaque clé.

</para>

<warning>

<para>

L'utilisation de cette fonction sans le paramètre <parameter>result</parameter>

est très fortement <emphasis>découragé</emphasis> et <emphasis>déconseillé</emphasis>

à partir de PHP 7.2.

À partir de PHP 8.0.0, le paramètre <parameter>result</parameter> est <emphasis>obligatoire</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> n'est plus optionnel.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

L'utilisation de <function>parse_str</function> sans le second argument

émet une note <constant>E_DEPRECATED</constant>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Exemple avec <function>parse_str</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

N'importe quel espace ou point dans les noms de paramètres est converti en tiret bas

lors de la création de clés de tableau ou de variables locales.

Ceci est dû au fait que les noms de variables en PHP ne peuvent pas contenir d'espaces

ou de points, mais cela s'applique même lors de l'utilisation de

cette fonction avec le paramètre <parameter>result</parameter> .

<example>

<title>Déformation des noms par <function>parse_str</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

La fonction <function>parse_str</function> est affectée par la directive

<link linkend="ini.max-input-vars">max_input_vars</link>.

Dépasser cette limite déclenche un avertissement <constant>E_WARNING</constant>,

et toute variable au-delà de cette limite n'est pas ajoutée au tableau de résultat.

La valeur par défaut est 1000 ; ajustez <link linkend="ini.max-input-vars">max_input_vars</link>

selon les besoins.

</para>

</note>

<note>

<para>

Toutes les valeurs ajoutées dans le tableau <parameter>result</parameter>

(ou les variables créées si le second paramètre n'est pas défini)

sont déjà décodées avec les mêmes règles que <function>urldecode</function>.

</para>

</note>

<note>

<para>

Pour obtenir la chaîne de requête de la requête actuelle, il est possible d'utiliser

la variable <varname>$_SERVER['QUERY_STRING']</varname>. En outre, l'on voudra

peut-être lire la section sur les

<link linkend="language.variables.external"> variables de sources externes</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>