archived-doc-fr/reference/strings/functions/parse-str.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: da15b6674ac1900c7d065bd746a04b53d7e963bf Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<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">
<![CDATA[
<?php
$str = "first=value&arr[]=foo+bar&arr[]=baz";

// Recommandé
parse_str($str, $output);
echo $output['first'], PHP_EOL;  // value
echo $output['arr'][0], PHP_EOL; // foo bar
echo $output['arr'][1], PHP_EOL; // baz
?>
]]>
    </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">
<![CDATA[
<?php
parse_str("My Value=Something", $output);
echo $output['My_Value']; // Something
?>
]]>
    </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>
<!-- 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
-->