Add access to full_path index of uploaded files

system/HTTP/Files/FileCollection.php

@@ -180,6 +180,7 @@ protected function createFileObject(array $array)
         return new UploadedFile(
             $array['tmp_name'] ?? null,
             $array['name'] ?? null,
+            $array['full_path'] ?? null,
             $array['type'] ?? null,
             $array['size'] ?? null,
             $array['error'] ?? null

system/HTTP/Files/UploadedFile.php

@@ -34,6 +34,13 @@ class UploadedFile extends File implements UploadedFileInterface
      */
     protected $path;
 
+    /**
+     * The webkit relative path of the file.
+     *
+     * @var string
+     */
+    protected $clientPath;
+
     /**
      * The original filename as provided by the client.
      *
@@ -75,13 +82,15 @@ class UploadedFile extends File implements UploadedFileInterface
      *
      * @param string $path         The temporary location of the uploaded file.
      * @param string $originalName The client-provided filename.
+     * @param string $clientPath   The webkit relative path of the uploaded file.
      * @param string $mimeType     The type of file as provided by PHP
      * @param int    $size         The size of the file, in bytes
      * @param int    $error        The error constant of the upload (one of PHP's UPLOADERRXXX constants)
      */
-    public function __construct(string $path, string $originalName, ?string $mimeType = null, ?int $size = null, ?int $error = null)
+    public function __construct(string $path, string $originalName, ?string $clientPath, ?string $mimeType = null, ?int $size = null, ?int $error = null)
     {
         $this->path             = $path;
+        $this->clientPath       = $clientPath;
         $this->name             = $originalName;
         $this->originalName     = $originalName;
         $this->originalMimeType = $mimeType;
@@ -267,6 +276,15 @@ public function getClientName(): string
         return $this->originalName;
     }
 
+    /**
+     * (PHP 8.1+)
+     * Returns the webkit relative path of the uploaded file on directory uploads.
+     */
+    public function getClientPath(): string|null
+    {
+        return $this->clientPath;
+    }
+
     /**
      * Gets the temporary filename where the file was uploaded to.
      */

system/HTTP/Files/UploadedFileInterface.php

@@ -28,11 +28,12 @@ interface UploadedFileInterface
      *
      * @param string $path         The temporary location of the uploaded file.
      * @param string $originalName The client-provided filename.
+     * @param string $clientPath   The webkit relative path of the uploaded file.
      * @param string $mimeType     The type of file as provided by PHP
      * @param int    $size         The size of the file, in bytes
      * @param int    $error        The error constant of the upload (one of PHP's UPLOADERRXXX constants)
      */
-    public function __construct(string $path, string $originalName, ?string $mimeType = null, ?int $size = null, ?int $error = null);
+    public function __construct(string $path, string $originalName, ?string $clientPath, ?string $mimeType = null, ?int $size = null, ?int $error = null);
 
     /**
      * Move the uploaded file to a new location.
@@ -109,6 +110,12 @@ public function getName(): string;
      */
     public function getTempName(): string;
 
+    /**
+     * (PHP 8.1+)
+     * Returns the webkit relative path of the uploaded file on directory uploads.
+     */
+    public function getClientPath(): string|null;
+
     /**
      * Returns the original file extension, based on the file name that
      * was uploaded. This is NOT a trusted source.

tests/system/HTTP/Files/FileCollectionTest.php

@@ -38,11 +38,12 @@ public function testAllReturnsValidSingleFile()
     {
         $_FILES = [
             'userfile' => [
-                'name'     => 'someFile.txt',
-                'type'     => 'text/plain',
-                'size'     => '124',
-                'tmp_name' => '/tmp/myTempFile.txt',
-                'error'    => 0,
+                'name'      => 'someFile.txt',
+                'type'      => 'text/plain',
+                'size'      => '124',
+                'tmp_name'  => '/tmp/myTempFile.txt',
+                'full_path' => 'tmp/myTempFile.txt',
+                'error'     => 0,
             ],
         ];
 
@@ -54,6 +55,7 @@ public function testAllReturnsValidSingleFile()
         $this->assertInstanceOf(UploadedFile::class, $file);
 
         $this->assertSame('someFile.txt', $file->getName());
+        $this->assertSame('tmp/myTempFile.txt', $file->getClientPath());
         $this->assertSame(124, $file->getSize());
     }
 

user_guide_src/source/libraries/uploaded_files.rst

@@ -304,6 +304,14 @@ version, use ``getMimeType()`` instead:
 
 .. literalinclude:: uploaded_files/015.php
 
+getClientPath()
+---------------
+
+Returns the `webkit relative path <https://developer.mozilla.org/en-US/docs/Web/API/File/webkitRelativePath>`_ of the uploaded file when the client has uploaded files via directory upload.  
+In PHP versions below 8.1, this returns ``null``
+
+.. literalinclude:: uploaded_files/023.php
+
 Moving Files
 ============
 

user_guide_src/source/libraries/uploaded_files/023.php

@@ -0,0 +1,4 @@
+<?php
+
+$clientPath = $file->getClientPath();
+echo $clientPath; // dir/file.txt, or dir/sub_dir/file.txt