[PHP 8.1] Documentation for full_path entry of $_FILES (#1130)

Co-authored-by: Yoshinari Takaoka <[email protected]>
Co-authored-by: Christoph M. Becker <[email protected]>

Author: 3 people

features/file-upload.xml

@@ -132,6 +132,15 @@
        </para>
       </listitem>
      </varlistentry>
+     <varlistentry>
+      <term><varname>$_FILES['userfile']['full_path']</varname></term>
+      <listitem>
+       <para>
+        The full path as submitted by the browser. This value does not always contain a real directory structure, and cannot be trusted.
+        Available as of PHP 8.1.0.
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
    </para>
 
@@ -462,6 +471,42 @@ foreach ($_FILES["pictures"]["error"] as $key => $error) {
      try to upload more files in one request than this limit.
     </simpara>
    </warning>
+   <para>
+    <example>
+     <title>Uploading an entire directory</title>
+     <simpara>
+      In HTML file upload fields, it is possible to upload an entire directory with the <literal>webkitdirectory</literal> attribute.
+      This feature is supported in most modern browsers.
+     </simpara>
+     <simpara>
+      With the <literal>full_path</literal> information, it is possible to store the relative paths,
+      or reconstruct the same directory in the server.
+     </simpara>
+     <programlisting role="html">
+<![CDATA[
+<form action="file-upload.php" method="post" enctype="multipart/form-data">
+  Send this directory:<br />
+  <input name="userfile[]" type="file" webkitdirectory multiple />
+  <input type="submit" value="Send files" />
+</form>
+]]>
+     </programlisting>
+    </example>
+
+    <warning>
+     <simpara>
+      The <literal>webkitdirectory</literal> attribute is non-standard and is not on a standards track.
+      Do not use it on production sites facing the Web: it will not work for every user.
+      There may also be large incompatibilities between implementations and the behavior may change in the future.
+     </simpara>
+     <simpara>
+      PHP only parses the relative path information submitted by the browser/user-agent,
+      and passes that information to the <varname>$_FILES</varname> array.
+      There is no guarantee that the values in the <literal>full_path</literal> array contains a real directory structure,
+      and the PHP application must not trust this information.
+     </simpara>
+    </warning>
+   </para>
   </sect1>
 
   <sect1 xml:id="features.file-upload.put-method">