Add access to full_path index of uploaded files

system/HTTP/Files/FileCollection.php

@@ -182,7 +182,8 @@ protected function createFileObject(array $array)
             $array['name'] ?? null,
             $array['type'] ?? null,
             $array['size'] ?? null,
-            $array['error'] ?? null
+            $array['error'] ?? null,
+            $array['full_path'] ?? 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.
      *
@@ -78,15 +85,17 @@ class UploadedFile extends File implements UploadedFileInterface
      * @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)
+     * @param string $clientPath   The webkit relative path of the uploaded file.
      */
-    public function __construct(string $path, string $originalName, ?string $mimeType = null, ?int $size = null, ?int $error = null)
+    public function __construct(string $path, string $originalName, ?string $mimeType = null, ?int $size = null, ?int $error = null, ?string $clientPath = null)
     {
         $this->path             = $path;
         $this->name             = $originalName;
         $this->originalName     = $originalName;
         $this->originalMimeType = $mimeType;
         $this->size             = $size;
         $this->error            = $error;
+        $this->clientPath       = $clientPath;
 
         parent::__construct($path, false);
     }
@@ -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
+    {
+        return $this->clientPath;
+    }
+
     /**
      * Gets the temporary filename where the file was uploaded to.
      */

system/HTTP/Files/UploadedFileInterface.php

@@ -31,8 +31,9 @@ interface UploadedFileInterface
      * @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)
+     * @param string $clientPath   The webkit relative path of the uploaded file.
      */
-    public function __construct(string $path, string $originalName, ?string $mimeType = null, ?int $size = null, ?int $error = null);
+    public function __construct(string $path, string $originalName, ?string $mimeType = null, ?int $size = null, ?int $error = null, ?string $clientPath = 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;
+
     /**
      * 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

@@ -453,6 +453,41 @@ public function testErrorWithNoError()
         $this->assertSame(UPLOAD_ERR_OK, $file->getError());
     }
 
+    public function testClientPathReturnsValidFullPath()
+    {
+        $_FILES = [
+            'userfile' => [
+                'name'      => 'someFile.txt',
+                'type'      => 'text/plain',
+                'size'      => '124',
+                'tmp_name'  => '/tmp/myTempFile.txt',
+                'full_path' => 'someDir/someFile.txt',
+            ],
+        ];
+
+        $collection = new FileCollection();
+        $file       = $collection->getFile('userfile');
+
+        $this->assertSame('someDir/someFile.txt', $file->getClientPath());
+    }
+
+    public function testClientPathReturnsNullWhenFullPathIsNull()
+    {
+        $_FILES = [
+            'userfile' => [
+                'name'     => 'someFile.txt',
+                'type'     => 'text/plain',
+                'size'     => '124',
+                'tmp_name' => '/tmp/myTempFile.txt',
+            ],
+        ];
+
+        $collection = new FileCollection();
+        $file       = $collection->getFile('userfile');
+
+        $this->assertNull($file->getClientPath());
+    }
+
     public function testFileReturnsValidSingleFile()
     {
         $_FILES = [

user_guide_src/source/changelogs/v4.4.0.rst

@@ -89,6 +89,9 @@ Libraries
   the actual validated data. See :ref:`validation-getting-validated-data` for details.
 - **Images:** The option ``$quality`` can now be used to compress WebP images.
 
+- **Uploaded Files:** Added ``UploadedFiles::getClientPath()`` method that returns
+  the value of the `full_path` index of the file if it was uploaded via directory upload.
+
 Helpers and Functions
 =====================
 

user_guide_src/source/libraries/uploaded_files.rst

@@ -304,6 +304,16 @@ version, use ``getMimeType()`` instead:
 
 .. literalinclude:: uploaded_files/015.php
 
+getClientPath()
+---------------
+
+.. versionadded:: 4.4.0
+
+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