Improve $_POST/$_GET definition (#4522)

* Improve $_POST/$_GET definition

* end example sentences with a dot

* $_GET: apply suggestions

* Do not use title case in refpurpose

* docs(post): reference php://input

* docs(php://input): provide example to read JSON data

* fix format in previous commits

* docs: apply suggestions

* docs: remove try/catch and improve variable names in example

Author: pereorga

language/predefined/variables/get.xml

@@ -4,15 +4,16 @@
 <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.
   </para>
  </refsect1>
 
@@ -29,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>
@@ -46,7 +47,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>

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>
@@ -44,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">

language/wrappers/php.xml

@@ -368,6 +368,28 @@ 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 raw JSON data from POST, PUT and
+    PATCH requests using <filename>php://input</filename>.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$input = file_get_contents("php://input");
+$json_array = json_decode(
+  json: $input,
+  associative: true,
+  flags: JSON_THROW_ON_ERROR
+);
+
+echo "Received JSON data: ";
+print_r($json_array);
+?>
 ]]>
    </programlisting>
   </example>