Merge pull request #7541 from JamminCoder/uploaded-file-full_path

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