bug #36905 and included some notes

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

features/file-upload.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.87 $ -->
+<!-- $Revision: 1.88 $ -->
  <chapter id="features.file-upload">
   <title>Handling file uploads</title>
 
@@ -460,46 +460,11 @@ foreach ($_FILES["pictures"]["error"] as $key => $error) {
 
   <sect1 id="features.file-upload.put-method">
    <title>PUT method support</title>
-   <simpara>
-    PUT method support has changed between PHP 3 and PHP 4.
-    In PHP 4, one should use the standard input stream to read
-    the contents of an HTTP PUT.
-   </simpara>
    <para>
-    <example>
-     <title>Saving HTTP PUT files with PHP 4</title>
-     <programlisting role="php">
-<![CDATA[
-<?php
-/* PUT data comes in on the stdin stream */
-$putdata = fopen("php://stdin", "r");
-
-/* Open a file for writing */
-$fp = fopen("myputfile.ext", "w");
-
-/* Read the data 1 KB at a time
-   and write to the file */
-while ($data = fread($putdata, 1024))
-  fwrite($fp, $data);
-
-/* Close the streams */
-fclose($fp);
-fclose($putdata);
-?>
-]]>
-     </programlisting>
-    </example>
-   </para>
-   <note>
-    <para>
-     All documentation below applies to PHP 3 only.
-    </para>
-   </note>
-   <para>
-    PHP provides support for the HTTP PUT method used by clients such
-    as <productname>Netscape Composer</productname> and W3C <productname>Amaya</productname>.  
-    PUT requests are much simpler
-    than a file upload and they look something like this:
+    PHP provides support for the HTTP PUT method used by some clients to store
+    files on a server.
+    PUT requests are much simpler than a file upload using POST requests
+    and they look something like this:
     <informalexample>
      <programlisting role="HTTP">
 <![CDATA[
@@ -529,24 +494,61 @@ Script PUT /put.php
    </para>
    <simpara>
     This tells Apache to send all PUT requests for URIs that match the
-    context in which you put this line to the put.php script.  This
+    context in which you put this line to the put.php script. This
     assumes, of course, that you have PHP enabled for the .php
-    extension and PHP is active.
+    extension and PHP is active. The destination resource for all PUT 
+    requests to this script has to be the script itself, not a filename the
+    uploaded file should have.
    </simpara>
    <simpara>
-    Inside your put.php file you would then do something like this:
+    With PHP 4 and following you would then do something like the following in
+    your put.php. This would copy the contents of the uploaded file to the
+    file <filename>myputfile.ext</filename> on the server.
+    You would probably want to perform some checks and/or
+    authenticate the user before performing this file copy.
    </simpara>
    <para>
-    <informalexample><programlisting role="php">
+    <example>
+     <title>Saving HTTP PUT files with PHP 4</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+/* PUT data comes in on the stdin stream */
+$putdata = fopen("php://input", "r");
+
+/* Open a file for writing */
+$fp = fopen("myputfile.ext", "w");
+
+/* Read the data 1 KB at a time
+   and write to the file */
+while ($data = fread($putdata, 1024))
+  fwrite($fp, $data);
+
+/* Close the streams */
+fclose($fp);
+fclose($putdata);
+?>
+]]>
+     </programlisting>
+    </example>
+   </para>
+   <note>
+    <para>
+     All documentation below applies to PHP 3 only.
+    </para>
+   </note>
+   <para>
+    <example>
+    <title>Saving HTTP PUT files with PHP 3</title>
+    <programlisting role="php">
 <![CDATA[
 <?php copy($PHP_UPLOADED_FILE_NAME, $DOCUMENT_ROOT . $REQUEST_URI); ?>
 ]]>
-    </programlisting></informalexample>
+    </programlisting>
+   </example>
    </para>
    <simpara>
-    This would copy the file to the location requested by the remote
-    client.  You would probably want to perform some checks and/or
-    authenticate the user before performing this file copy.  The only
+    The only
     trick here is that when PHP sees a PUT-method request it stores
     the uploaded file in a temporary file just like those handled by
     the <link