From c3dee13df9ce64407d824cf782a45114641a50d0 Mon Sep 17 00:00:00 2001
From: Pere Orga <pere@orga.cat>
Date: Fri, 7 Mar 2025 16:55:29 +0100
Subject: [PATCH 1/9] Improve $_POST/$_GET definition

---
 language/predefined/variables/get.xml  | 12 +++++++-----
 language/predefined/variables/post.xml |  5 +++--
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/language/predefined/variables/get.xml b/language/predefined/variables/get.xml
index 8d0663992d35..3d751616154a 100644
--- a/language/predefined/variables/get.xml
+++ b/language/predefined/variables/get.xml
@@ -4,15 +4,17 @@
 <refentry role="variable" xml:id="reserved.variables.get" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>$_GET</refname>
-  <refpurpose>HTTP GET variables</refpurpose>
+  <refpurpose>Query String Variables</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
   &reftitle.description;
   <para>
-   An associative array of variables passed to the current script
-   via the URL parameters (aka. query string). Note that the array is  not only
-   populated for GET requests, but rather for all requests with a query string.
+   An associative array of variables passed to the current script via the URL
+   parameters (also known as the query string). Note that this array is
+   populated whenever a query string is present, regardless of the HTTP request
+   method. Even in POST, PUT, or other types of requests, query string
+   parameters will still be available in <varname>$_GET</varname>.
   </para>
  </refsect1>
  
@@ -46,7 +48,7 @@ Hello Hannes!
   &note.is-superglobal;
   <note>
    <para>
-    The GET variables are passed through <function>urldecode</function>.
+    The values in <varname>$_GET</varname> are automatically passed through <function>urldecode</function>.
    </para>
   </note>
  </refsect1>
diff --git a/language/predefined/variables/post.xml b/language/predefined/variables/post.xml
index 3ffe08affece..15b8c5f8e2e2 100644
--- a/language/predefined/variables/post.xml
+++ b/language/predefined/variables/post.xml
@@ -4,7 +4,7 @@
 <refentry role="variable" xml:id="reserved.variables.post" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>$_POST</refname>
-  <refpurpose>HTTP POST variables</refpurpose>
+  <refpurpose>Form Data from HTTP POST Requests</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
@@ -29,7 +29,8 @@ echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
 ]]>
     </programlisting>
     <simpara>
-     Assuming the user POSTed name=Hannes
+     Assuming the user sent a POST request with <literal>name=Hannes</literal>
+     in the body:
     </simpara>
     &example.outputs.similar;
     <screen>

From 34704c6999d7e1a180507b0f7a1d4affee4daa58 Mon Sep 17 00:00:00 2001
From: Pere Orga <pere@orga.cat>
Date: Fri, 7 Mar 2025 16:57:42 +0100
Subject: [PATCH 2/9] end example sentences with a dot

---
 language/predefined/variables/get.xml  | 2 +-
 language/predefined/variables/post.xml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/language/predefined/variables/get.xml b/language/predefined/variables/get.xml
index 3d751616154a..456719a138dc 100644
--- a/language/predefined/variables/get.xml
+++ b/language/predefined/variables/get.xml
@@ -31,7 +31,7 @@ echo 'Hello ' . htmlspecialchars($_GET["name"]) . '!';
 ]]>
     </programlisting>
     <simpara>
-     Assuming the user entered http://example.com/?name=Hannes
+     Assuming the user entered http://example.com/?name=Hannes.
     </simpara>
     &example.outputs.similar;
     <screen>
diff --git a/language/predefined/variables/post.xml b/language/predefined/variables/post.xml
index 15b8c5f8e2e2..0ad8be1f5e8f 100644
--- a/language/predefined/variables/post.xml
+++ b/language/predefined/variables/post.xml
@@ -30,7 +30,7 @@ echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
     </programlisting>
     <simpara>
      Assuming the user sent a POST request with <literal>name=Hannes</literal>
-     in the body:
+     in the body.
     </simpara>
     &example.outputs.similar;
     <screen>

From 2e864fac84958d43eed10bf1c4eb53d7c05f7319 Mon Sep 17 00:00:00 2001
From: Pere Orga <pere@orga.cat>
Date: Sun, 9 Mar 2025 17:20:22 +0100
Subject: [PATCH 3/9] $_GET: apply suggestions

---
 language/predefined/variables/get.xml | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/language/predefined/variables/get.xml b/language/predefined/variables/get.xml
index 456719a138dc..c16e8765cbb6 100644
--- a/language/predefined/variables/get.xml
+++ b/language/predefined/variables/get.xml
@@ -13,8 +13,7 @@
    An associative array of variables passed to the current script via the URL
    parameters (also known as the query string). Note that this array is
    populated whenever a query string is present, regardless of the HTTP request
-   method. Even in POST, PUT, or other types of requests, query string
-   parameters will still be available in <varname>$_GET</varname>.
+   method.
   </para>
  </refsect1>
  
@@ -31,7 +30,7 @@ echo 'Hello ' . htmlspecialchars($_GET["name"]) . '!';
 ]]>
     </programlisting>
     <simpara>
-     Assuming the user entered http://example.com/?name=Hannes.
+     Assuming the user entered <literal>http://example.com/?name=Hannes</literal>.
     </simpara>
     &example.outputs.similar;
     <screen>

From 063c47ab375d1411d0bbe2a9810f229186c647e1 Mon Sep 17 00:00:00 2001
From: Pere Orga <pere@orga.cat>
Date: Mon, 10 Mar 2025 07:23:22 +0100
Subject: [PATCH 4/9] Do not use title case in refpurpose

---
 language/predefined/variables/get.xml  | 2 +-
 language/predefined/variables/post.xml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/language/predefined/variables/get.xml b/language/predefined/variables/get.xml
index c16e8765cbb6..8b3f0160a3c8 100644
--- a/language/predefined/variables/get.xml
+++ b/language/predefined/variables/get.xml
@@ -4,7 +4,7 @@
 <refentry role="variable" xml:id="reserved.variables.get" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>$_GET</refname>
-  <refpurpose>Query String Variables</refpurpose>
+  <refpurpose>Query string variables</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
diff --git a/language/predefined/variables/post.xml b/language/predefined/variables/post.xml
index 0ad8be1f5e8f..65c100ce58a3 100644
--- a/language/predefined/variables/post.xml
+++ b/language/predefined/variables/post.xml
@@ -4,7 +4,7 @@
 <refentry role="variable" xml:id="reserved.variables.post" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>$_POST</refname>
-  <refpurpose>Form Data from HTTP POST Requests</refpurpose>
+  <refpurpose>Form data from HTTP POST requests</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">

From 913d651fba489ec0dee56352986acf00271f6c29 Mon Sep 17 00:00:00 2001
From: Pere Orga <pere@orga.cat>
Date: Mon, 10 Mar 2025 23:03:37 +0100
Subject: [PATCH 5/9] docs(post): reference php://input

---
 language/predefined/variables/post.xml | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/language/predefined/variables/post.xml b/language/predefined/variables/post.xml
index 65c100ce58a3..da40140ac76b 100644
--- a/language/predefined/variables/post.xml
+++ b/language/predefined/variables/post.xml
@@ -45,6 +45,17 @@ Hello Hannes!
  <refsect1 role="notes">
   &reftitle.notes;
   &note.is-superglobal;
+  <note>
+   <simpara>
+    To read POST data sent with other content types (e.g.
+    <literal>application/json</literal> or <literal>application/xml</literal>)
+    <link linkend="wrappers.php.input"><filename>php://input</filename></link>
+    must be used. Unlike <varname>$_POST</varname>, which only works with
+    <literal>application/x-www-form-urlencoded</literal> and
+    <literal>multipart/form-data</literal>, <filename>php://input</filename>
+    provides direct access to the raw data from the body of the request.
+   <simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="seealso">

From 4bc83e00a62787c7b11af8148ffa9fca2c651d6d Mon Sep 17 00:00:00 2001
From: Pere Orga <pere@orga.cat>
Date: Mon, 10 Mar 2025 23:04:23 +0100
Subject: [PATCH 6/9] docs(php://input): provide example to read JSON data

---
 language/wrappers/php.xml | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/language/wrappers/php.xml b/language/wrappers/php.xml
index 7c1295122d65..c04b8239a9e7 100644
--- a/language/wrappers/php.xml
+++ b/language/wrappers/php.xml
@@ -368,6 +368,31 @@ file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello
 <?php
 file_put_contents('php://memory', 'PHP');
 echo file_get_contents('php://memory'); // prints nothing
+]]>
+   </programlisting>
+  </example>
+  <example>
+   <title>php://input to read JSON data from the request body</title>
+   <para>
+    This example demonstrates how to read JSON data from POST, PUT and PATCH
+    requests using <filename>php://input</filename>.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+header('Content-Type: text/plain');
+
+// Read raw input data from php://input
+$jsonData = file_get_contents("php://input");
+
+// Decode JSON data into a PHP array
+$data = json_decode($jsonData, true);
+if ($data !== null) {
+  echo "Received JSON data:\n";
+  print_r($data);
+} else {
+  echo "Invalid JSON.";
+}
 ]]>
    </programlisting>
   </example>

From 3590ba9bc942cb4180cadf50c1349e7aae399910 Mon Sep 17 00:00:00 2001
From: Pere Orga <pere@orga.cat>
Date: Mon, 10 Mar 2025 23:10:43 +0100
Subject: [PATCH 7/9] fix format in previous commits

---
 language/predefined/variables/post.xml | 2 +-
 language/wrappers/php.xml              | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/language/predefined/variables/post.xml b/language/predefined/variables/post.xml
index da40140ac76b..b74304ee8d30 100644
--- a/language/predefined/variables/post.xml
+++ b/language/predefined/variables/post.xml
@@ -54,7 +54,7 @@ Hello Hannes!
     <literal>application/x-www-form-urlencoded</literal> and
     <literal>multipart/form-data</literal>, <filename>php://input</filename>
     provides direct access to the raw data from the body of the request.
-   <simpara>
+   </simpara>
   </note>
  </refsect1>
 
diff --git a/language/wrappers/php.xml b/language/wrappers/php.xml
index c04b8239a9e7..585a9f11a6f2 100644
--- a/language/wrappers/php.xml
+++ b/language/wrappers/php.xml
@@ -393,6 +393,7 @@ if ($data !== null) {
 } else {
   echo "Invalid JSON.";
 }
+?>
 ]]>
    </programlisting>
   </example>

From 70039d295e3aca31896ab5d2d74c40459f710b4b Mon Sep 17 00:00:00 2001
From: Pere Orga <pere@orga.cat>
Date: Tue, 11 Mar 2025 00:39:59 +0100
Subject: [PATCH 8/9] docs: apply suggestions

---
 language/wrappers/php.xml | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/language/wrappers/php.xml b/language/wrappers/php.xml
index 585a9f11a6f2..348d97675025 100644
--- a/language/wrappers/php.xml
+++ b/language/wrappers/php.xml
@@ -374,24 +374,25 @@ echo file_get_contents('php://memory'); // prints nothing
   <example>
    <title>php://input to read JSON data from the request body</title>
    <para>
-    This example demonstrates how to read JSON data from POST, PUT and PATCH
-    requests using <filename>php://input</filename>.
+    This example demonstrates how to read raw JSON data from POST, PUT and
+    PATCH requests using <filename>php://input</filename>.
    </para>
    <programlisting role="php">
 <![CDATA[
 <?php
-header('Content-Type: text/plain');
+$jsonString = file_get_contents("php://input");
 
-// Read raw input data from php://input
-$jsonData = file_get_contents("php://input");
+try {
+  $data = json_decode(
+      json: $jsonString,
+      associative: true,
+      flags: JSON_THROW_ON_ERROR
+  );
 
-// Decode JSON data into a PHP array
-$data = json_decode($jsonData, true);
-if ($data !== null) {
-  echo "Received JSON data:\n";
+  echo "Received JSON data: ";
   print_r($data);
-} else {
-  echo "Invalid JSON.";
+} catch (JsonException $e) {
+  echo "Invalid JSON: " . $e->getMessage();
 }
 ?>
 ]]>

From 2a73421fec9e2a027e4eabc4a0ad10c947cf88a7 Mon Sep 17 00:00:00 2001
From: Pere Orga <pere@orga.cat>
Date: Tue, 11 Mar 2025 08:44:50 +0100
Subject: [PATCH 9/9] docs: remove try/catch and improve variable names in
 example

---
 language/wrappers/php.xml | 21 ++++++++-------------
 1 file changed, 8 insertions(+), 13 deletions(-)

diff --git a/language/wrappers/php.xml b/language/wrappers/php.xml
index 348d97675025..3a03bb46f985 100644
--- a/language/wrappers/php.xml
+++ b/language/wrappers/php.xml
@@ -380,20 +380,15 @@ echo file_get_contents('php://memory'); // prints nothing
    <programlisting role="php">
 <![CDATA[
 <?php
-$jsonString = file_get_contents("php://input");
+$input = file_get_contents("php://input");
+$json_array = json_decode(
+  json: $input,
+  associative: true,
+  flags: JSON_THROW_ON_ERROR
+);
 
-try {
-  $data = json_decode(
-      json: $jsonString,
-      associative: true,
-      flags: JSON_THROW_ON_ERROR
-  );
-
-  echo "Received JSON data: ";
-  print_r($data);
-} catch (JsonException $e) {
-  echo "Invalid JSON: " . $e->getMessage();
-}
+echo "Received JSON data: ";
+print_r($json_array);
 ?>
 ]]>
    </programlisting>