Skip to content

Modernise parse_str description #4556

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 6, 2025
Merged

Modernise parse_str description #4556

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8e5f723
Modernise parse_str description
IMSoP Mar 22, 2025
7ce8e1f
parse_str: tweak wording for easier reading
IMSoP Mar 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 17 additions & 12 deletions reference/strings/functions/parse-str.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<refentry xml:id="function.parse-str" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>parse_str</refname>
<refpurpose>Parses the string into variables</refpurpose>
<refpurpose>Parse a string as a URL query string</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -15,8 +15,9 @@
</methodsynopsis>
<para>
Parses <parameter>string</parameter> as if it were the query string
passed via a URL and sets variables in the current scope (or in the array
if <parameter>result</parameter> is provided).
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>

Expand All @@ -36,8 +37,10 @@
<term><parameter>result</parameter></term>
<listitem>
<para>
If the second parameter <parameter>result</parameter> is present,
variables are stored in this variable as array elements instead.
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>
Expand Down Expand Up @@ -118,9 +121,10 @@ echo $arr[1]; // baz
</example>
</para>
<para>
Because variables in PHP can't have dots and spaces in their names,
those are converted to underscores. Same applies to naming of
respective key names in case of using this function with
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>
Expand All @@ -144,7 +148,7 @@ echo $output['My_Value']; // Something

<note>
<para>
<function>parse_str()</function> is affected by the <link linkend="ini.max-input-vars">max_input_vars</link>
<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.
Expand All @@ -153,13 +157,14 @@ echo $output['My_Value']; // Something

<note>
<para>
All variables created (or values returned into array if second parameter is set)
are already <function>urldecode</function>d.
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 current <literal>QUERY_STRING</literal>, you may use the variable
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
Expand Down