Create stub for request_parse_body() (#4108)

Co-authored-by: Ilija Tovilo <ilija.tovilo@me.com>

language/errors/php7.xml

@@ -75,6 +75,9 @@
        <listitem>
         <simpara><classname>FiberError</classname></simpara>
        </listitem>
+       <listitem>
+        <simpara><classname>RequestParseBodyException</classname></simpara>
+       </listitem>
       </itemizedlist>
      </listitem>
      <listitem>

language/predefined/exceptions.xml

@@ -27,6 +27,7 @@
  &language.predefined.valueerror;
  &language.predefined.unhandledmatcherror;
  &language.predefined.fibererror;
+ &language.predefined.requestparsebodyexception;
 </part>
 
 <!-- Keep this comment at the end of the file

language/predefined/requestparsebodyexception.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<reference xml:id="class.requestparsebodyexception" role="exception" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>RequestParseBodyException</title>
+ <titleabbrev>RequestParseBodyException</titleabbrev>
+
+ <partintro>
+
+<!-- {{{ Exception intro -->
+  <section xml:id="RequestParseBodyException.intro">
+   &reftitle.intro;
+   <simpara>
+    A <classname>RequestParseBodyException</classname> is thrown in
+    <function>request_parse_body</function> when the request body is invalid,
+    according to the <literal>Content-Type</literal> header.
+   </simpara>
+  </section>
+<!-- }}} -->
+
+  <section xml:id="RequestParseBodyException.synopsis">
+   &reftitle.classsynopsis;
+
+<!-- {{{ Synopsis -->
+   <classsynopsis class="class">
+    <ooexception>
+     <exceptionname>RequestParseBodyException</exceptionname>
+    </ooexception>
+
+    <ooclass>
+     <modifier>extends</modifier>
+     <classname>Exception</classname>
+    </ooclass>
+
+    <classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;']]))">
+     <xi:fallback/>
+    </xi:include>
+
+    <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='Exception'])">
+     <xi:fallback/>
+    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Exception'])">
+     <xi:fallback/>
+    </xi:include>
+   </classsynopsis>
+
+<!-- }}} -->
+
+  </section>
+ </partintro>
+</reference>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

language/predefined/versions.xml

@@ -101,6 +101,8 @@
 
  <function name="closedgeneratorexception" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8"/>
 
+ <function name="requstparsebodyexception" from="PHP 8 &gt;= 8.4.0"/>
+
  <function name="fiber" from="PHP 8 &gt;= 8.1.0"/>
  <function name="fiber::__construct" from="PHP 8 &gt;= 8.1.0"/>
  <function name="fiber::start" from="PHP 8 &gt;= 8.1.0"/>

reference/network/functions/request-parse-body.xml

@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="function.request-parse-body" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>request_parse_body</refname>
+  <refpurpose>Read and parse the request body and return the result</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>array</type><methodname>request_parse_body</methodname>
+   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
+  </methodsynopsis>
+  <simpara>
+   This function reads the request body and parses it according to the
+   <literal>Content-Type</literal> header. Currently, two content types are
+   supported:
+  </simpara>
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     <literal>application/x-www-form-urlencoded</literal>
+    </simpara>
+   </listitem>
+   <listitem>
+    <simpara>
+     <literal>multipart/form-data</literal>
+    </simpara>
+   </listitem>
+  </itemizedlist>
+  <simpara>
+   This function is used primarily to parse
+   <literal>multipart/form-data</literal> requests with HTTP verbs other than
+   <literal>POST</literal> which do not automatically populate the
+   <varname>$_POST</varname> and <varname>$_FILES</varname> superglobals.
+  </simpara>
+
+  <caution>
+   <simpara>
+    <function>request_parse_body</function> consumes the request body without
+    buffering it to the <literal>php://input</literal> stream.
+   </simpara>
+  </caution>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>options</parameter></term>
+    <listitem>
+     <simpara>
+      The <parameter>options</parameter> parameter accepts an associative array
+      to override the following global &php.ini; settings for parsing of the
+      request body.
+     </simpara>
+     <itemizedlist>
+      <listitem><simpara><literal>max_file_uploads</literal></simpara></listitem>
+      <listitem><simpara><literal>max_input_vars</literal></simpara></listitem>
+      <listitem><simpara><literal>max_multipart_body_parts</literal></simpara></listitem>
+      <listitem><simpara><literal>post_max_size</literal></simpara></listitem>
+      <listitem><simpara><literal>upload_max_filesize</literal></simpara></listitem>
+     </itemizedlist>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   <function>request_parse_body</function> returns an array pair with the
+   equivalent of <varname>$_POST</varname> at index <literal>0</literal> and
+   <varname>$_FILES</varname> at index <literal>1</literal>.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simpara>
+   When the request body is invalid,
+   according to the <literal>Content-Type</literal> header,
+   a <exceptionname>RequestParseBodyException</exceptionname> is thrown.
+  </simpara>
+  <simpara>
+   A <exceptionname>ValueError</exceptionname> is thrown when
+   <parameter>options</parameter> contains invalid keys,
+   or invalid values for the corresponding key.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example xml:id="function.request-parse-body.example.basic">
+   <title><function>request_parse_body</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+// Parse request and store result in the $_POST and $_FILES superglobals.
+[$_POST, $_FILES] = request_parse_body();
+// Echo the content of some transferred file
+echo file_get_contents($_FILES['file_name']['tmp_name']);
+?>
+]]>
+   </programlisting>
+  </example>
+  <example xml:id="function.request-parse-body.example.options">
+   <title><function>request_parse_body</function> example with customized options</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+// form.php
+
+assert_logged_in();
+
+// Only for this form, we allow a bigger upload size.
+[$_POST, $_FILES] = request_parse_body([
+    'post_max_size' => '10M',
+    'upload_max_filesize' => '10M',
+]);
+
+// Do something with the uploaded files.
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

reference/network/versions.xml

@@ -34,6 +34,7 @@
  <function name="net_get_interfaces" from="PHP 7 &gt;= 7.3, PHP 8"/>
  <function name="openlog" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="pfsockopen" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
+ <function name="request_parse_body" from="PHP 8 &gt;= 8.4.0"/>
  <function name="setcookie" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="setrawcookie" from="PHP 5, PHP 7, PHP 8"/>
  <function name="socket_get_status" from="PHP 4, PHP 5, PHP 7, PHP 8"/>