From 8e5f7233a7441708b7ebe03c114192645d50c071 Mon Sep 17 00:00:00 2001
From: Rowan Tommins <rowan.collins@gmail.com>
Date: Sat, 22 Mar 2025 15:46:16 +0000
Subject: [PATCH 1/2] Modernise parse_str description

Most of the text still acted as though "create a bunch of local variables" was the normal behaviour, even though it's been discouraged for years, and isn't even supported in PHP 8.

There were also a few incorrect or questionable uses of markup.
---
 reference/strings/functions/parse-str.xml | 29 +++++++++++++----------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/reference/strings/functions/parse-str.xml b/reference/strings/functions/parse-str.xml
index 9b03d2e3d4eb..38bfdb48b92c 100644
--- a/reference/strings/functions/parse-str.xml
+++ b/reference/strings/functions/parse-str.xml
@@ -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">
@@ -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>
 
@@ -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>
@@ -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 variables in PHP can't have dots and spaces in their names,
+   but applies even when using this function with the recommended
    <parameter>result</parameter> parameter.   
    <example>
     <title><function>parse_str</function> name mangling</title>
@@ -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.
@@ -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 as though run through <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

From 7ce8e1f1386da58a2e8640bcb7fa3320a259d50f Mon Sep 17 00:00:00 2001
From: Rowan Tommins <rowan.collins@gmail.com>
Date: Sun, 23 Mar 2025 17:01:36 +0000
Subject: [PATCH 2/2] parse_str: tweak wording for easier reading

---
 reference/strings/functions/parse-str.xml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/reference/strings/functions/parse-str.xml b/reference/strings/functions/parse-str.xml
index 38bfdb48b92c..5102fe7b2299 100644
--- a/reference/strings/functions/parse-str.xml
+++ b/reference/strings/functions/parse-str.xml
@@ -123,8 +123,8 @@ echo $arr[1]; // baz
   <para>
    Any spaces and dots in parameter names are converted to underscores
    when creating array keys or local variables.
-   This is because variables in PHP can't have dots and spaces in their names,
-   but applies even when using this function with the recommended
+   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>
@@ -159,7 +159,7 @@ echo $output['My_Value']; // Something
    <para>
     All values populated in the <parameter>result</parameter> array
     (or variables created if second parameter is not set)
-    are already URL-decoded as though run through <function>urldecode</function>.
+    are already URL-decoded using the same rules as <function>urldecode</function>.
    </para>
   </note>
   <note>