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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.parse-str" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>parse_str</refname>
  <refpurpose>Parse a string as a URL query string</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>
   Parses <parameter>string</parameter> as if it were the query string
   passed via a URL and sets keys in the provided <parameter>result</parameter>
   array. If no <parameter>result</parameter> is passed, values are instead
   set as variables in the current scope.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       The input string.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>result</parameter></term>
     <listitem>
      <para>
       A variable passed by reference, which will be set to an array
       containing the key-value pairs extracted from <parameter>string</parameter>.
       If the <parameter>result</parameter> parameter is not passed,
       a separate variable is set in the local scope for each key.
      </para>

      <warning>
       <para>
        Using this function without the <parameter>result</parameter> parameter is highly
        <emphasis>DISCOURAGED</emphasis> and <emphasis>DEPRECATED</emphasis> as of PHP 7.2.
        As of PHP 8.0.0, the <parameter>result</parameter> parameter is <emphasis>mandatory</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> is no longer optional.
      </entry>
     </row>
      <row>
       <entry>7.2.0</entry>
       <entry>
        Usage of <function>parse_str</function> without a second parameter
        now emits an <constant>E_DEPRECATED</constant> notice.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Using <function>parse_str</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$str = "first=value&arr[]=foo+bar&arr[]=baz";

// Recommended
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>
   Any spaces and dots in parameter names are converted to underscores
   when creating array keys or local variables.
   This is because variable names in PHP are not allowed to contain spaces
   or dots, but applies even when using this function with the recommended
   <parameter>result</parameter> parameter.   
   <example>
    <title><function>parse_str</function> name mangling</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>
    <function>parse_str</function> is affected by the <link linkend="ini.max-input-vars">max_input_vars</link>
    directive. Exceeding this limit triggers an <constant>E_WARNING</constant>,
    and any variables beyond the limit are not added to the result array.
    The default is 1000; adjust <link linkend="ini.max-input-vars">max_input_vars</link> as needed.
   </para>
  </note>

  <note>
   <para>
    All values populated in the <parameter>result</parameter> array
    (or variables created if second parameter is not set)
    are already URL-decoded using the same rules as <function>urldecode</function>.
   </para>
  </note>
  <note>
   <para>
    To get the query string of the current request, you may use the variable
    <varname>$_SERVER['QUERY_STRING']</varname>.
    Also, you may want to read the section on
    <link linkend="language.variables.external">variables from external
    sources</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
-->