- php://input and how many times it can be read.

- Closes bug #52180

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@303169 c90b9560-bf6c-de11-be94-00142212c4b1

appendices/wrappers.xml

@@ -428,16 +428,26 @@ X-MyCustomHeader: Foo
    <function>print</function> and <function>echo</function>.
   </simpara>
   <simpara>
-   <filename>php://input</filename> allows you to read raw POST data.
-   It is a less memory intensive alternative to
-   <varname>$HTTP_RAW_POST_DATA</varname> and does not need any
-   special &php.ini; directives.
+   <filename>php://input</filename> allows you to read raw data
+   from the request body.
+   In case of POST requests, it preferrable to
+   <varname>$HTTP_RAW_POST_DATA</varname> as it does not depend on
+   special &php.ini; directives. Moreover, for those cases where
+   <varname>$HTTP_RAW_POST_DATA</varname> is not populated by
+   default, it is a potentially less memory intensive alternative
+   than activating <link linkend="ini.always-populate-raw-post-data">allways_populate_raw_post_data</link>.
    <filename>php://input</filename> is not available with
    <literal>enctype="multipart/form-data"</literal>.
   </simpara>
   <note>
    <simpara>
-    <filename>php://input</filename> can only be read once.
+    A stream opened with <filename>php://input</filename> can only be read
+	once; the stream does not support seek operations. However, depending
+	on the SAPI implementation, it may be possible to open another
+	<filename>php://input</filename> stream and restart reading. This is
+	only possible if the request body data has been saved. Typically, this
+	is the case for POST requests, but not other request methods, such as
+	PUT or PROPFIND.
    </simpara>
   </note>
   <simpara>