From 869dac5146e1ef7fd6853d8962ef3ca16e731d27 Mon Sep 17 00:00:00 2001
From: Sergey Panteleev <sergey@php.net>
Date: Tue, 23 Nov 2021 11:02:54 +0300
Subject: [PATCH 1/3] [PHP 8.1] Documentation full_path entry of $_FILES

---
 features/file-upload.xml | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/features/file-upload.xml b/features/file-upload.xml
index 0da46e3a5e3c..359f1317ae70 100644
--- a/features/file-upload.xml
+++ b/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.
+        Available as of PHP 8.1.0.
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
    </para>
 
@@ -462,6 +471,37 @@ 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>
+      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 applications must not trust this information.
+     </simpara>
+    </warning>
+   </para>
   </sect1>
 
   <sect1 xml:id="features.file-upload.put-method">

From cc7ea931913bea8218a1a114e0281182e04fb8da Mon Sep 17 00:00:00 2001
From: Sergey Panteleev <sergey@php.net>
Date: Thu, 9 Dec 2021 09:18:34 +0300
Subject: [PATCH 2/3] Apply suggestions from code review

Co-authored-by: Yoshinari Takaoka <mumumu@mumumu.org>
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
---
 features/file-upload.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/features/file-upload.xml b/features/file-upload.xml
index 359f1317ae70..d36fb3f6cb8d 100644
--- a/features/file-upload.xml
+++ b/features/file-upload.xml
@@ -136,7 +136,7 @@
       <term><varname>$_FILES['userfile']['full_path']</varname></term>
       <listitem>
        <para>
-        The full path as submitted by the browser.
+        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>
@@ -498,7 +498,7 @@ foreach ($_FILES["pictures"]["error"] as $key => $error) {
       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 applications must not trust this information.
+      and the PHP application must not trust this information.
      </simpara>
     </warning>
    </para>

From 3c7b2c005675daeea92e6f84565e94ebfb28f15f Mon Sep 17 00:00:00 2001
From: Sergey Panteleev <sergey@php.net>
Date: Thu, 9 Dec 2021 09:28:46 +0300
Subject: [PATCH 3/3] add warning about non-standard feature

---
 features/file-upload.xml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/features/file-upload.xml b/features/file-upload.xml
index d36fb3f6cb8d..e69a7a61c3a8 100644
--- a/features/file-upload.xml
+++ b/features/file-upload.xml
@@ -494,6 +494,11 @@ foreach ($_FILES["pictures"]["error"] as $key => $error) {
     </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.