From cdae2fe1137d875ec4fdf877f0543fec7687f872 Mon Sep 17 00:00:00 2001
From: sy-records <52o@qq52o.cn>
Date: Sat, 22 Nov 2025 13:55:50 +0800
Subject: [PATCH] Improve $_POST definition

---
 language/predefined/variables/post.xml | 17 ++++++++++++++---
 language/wrappers/php.xml              | 24 +++++++++++++++++++++++-
 2 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/language/predefined/variables/post.xml b/language/predefined/variables/post.xml
index 6c7337446..4ab9c42b6 100644
--- a/language/predefined/variables/post.xml
+++ b/language/predefined/variables/post.xml
@@ -1,11 +1,12 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a6d209f4ff71ccba3f1255902827f5df3e092ff9 Maintainer: daijie Status: ready -->
+<!-- EN-Revision: f56de7ebe7a1a85ce9e44a2bf6b77b07adfe3ae4 Maintainer: daijie Status: ready -->
+<!-- CREDITS: Luffy -->
 
 <refentry role="variable" xml:id="reserved.variables.post" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="verify_info:false">
  <refnamediv>
   <refname>$_POST</refname>
-  <refpurpose>HTTP POST 变量</refpurpose>
+  <refpurpose>来自 HTTP POST 请求的表单数据</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
@@ -28,7 +29,7 @@ echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
 ]]>
     </programlisting>
     <simpara>
-     假设用户通过 HTTP POST 方式传递了参数 name=Hannes
+     假设用户发送了一个包含 <literal>name=Hannes</literal> 的 POST 请求体。
     </simpara>
     &example.outputs.similar;
     <screen>
@@ -43,6 +44,16 @@ Hello Hannes!
  <refsect1 role="notes">
   &reftitle.notes;
   &note.is-superglobal;
+  <note>
+   <simpara>
+    读取与其他内容类型一起发送的 POST 数据（例如
+    <literal>application/json</literal> 或 <literal>application/xml</literal>）
+    必须使用 <link linkend="wrappers.php.input"><filename>php://input</filename></link>。
+    与仅适用于 <literal>application/x-www-form-urlencoded</literal> 和
+    <literal>multipart/form-data</literal> 的 <varname>$_POST</varname> 不同，
+    <filename>php://input</filename> 提供对请求正文中原始数据的直接访问。
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="seealso">
diff --git a/language/wrappers/php.xml b/language/wrappers/php.xml
index f8fd07742..b69296dd3 100644
--- a/language/wrappers/php.xml
+++ b/language/wrappers/php.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 0592e6316d3869b49637df29c471097e7bf78592 Maintainer: daijie Status: ready -->
+<!-- EN-Revision: f56de7ebe7a1a85ce9e44a2bf6b77b07adfe3ae4 Maintainer: daijie Status: ready -->
 <!-- CREDITS: Luffy, mowangjuanzi -->
 <refentry xml:id="wrappers.php" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="verify_info:false" role="stream_wrapper">
  <refnamediv>
@@ -335,6 +335,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'); // 啥也没有
+]]>
+   </programlisting>
+  </example>
+  <example>
+   <title>php://input 从请求体中读取 JSON 数据</title>
+   <para>
+    此例演示了如何使用 <filename>php://input</filename>
+    读取 POST、PUT 和 PATCH 请求中的原始 JSON 数据。
+   </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>