feature #19216 [HttpFoundation] Add UploadedFile::getClientOriginalPath() to support directory uploads (danielburger1337)

This PR was squashed before being merged into the 7.1 branch.

Discussion
----------

[HttpFoundation] Add `UploadedFile::getClientOriginalPath()` to support directory uploads

See #19212 and symfony/symfony#52493

Edit: I just realized that `@alexandre`-daubois created PR #19215 for this as well.
Just for the record, I don't care which one gets merged.

Commits
-------

4120857 [HttpFoundation] Add `UploadedFile::getClientOriginalPath()` to support directory uploads

Author: OskarStark

controller/upload_file.rst

@@ -194,13 +194,23 @@ There are some important things to consider in the code of the above controller:
    users. This also applies to the files uploaded by your visitors. The ``UploadedFile``
    class provides methods to get the original file extension
    (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getClientOriginalExtension`),
-   the original file size (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getSize`)
-   and the original file name (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getClientOriginalName`).
+   the original file size (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getSize`),
+   the original file name (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getClientOriginalName`)
+   and the original file path (:method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::getClientOriginalPath`).
    However, they are considered *not safe* because a malicious user could tamper
    that information. That's why it's always better to generate a unique name and
    use the :method:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile::guessExtension`
    method to let Symfony guess the right extension according to the file MIME type;
 
+.. note::
+
+    If a directory was uploaded, ``getClientOriginalPath`` will contain the **webkitRelativePath** as provided by the browser.
+    Otherwise this value will be identical to ``getClientOriginalName``.
+
+.. versionadded:: 7.1
+
+    The ``getClientOriginalPath`` method was introduced in Symfony 7.1.
+
 You can use the following code to link to the PDF brochure of a product:
 
 .. code-block:: html+twig

reference/forms/types/file.rst

@@ -55,6 +55,10 @@ You might calculate the filename in one of the following ways::
     // use the original file name
     $file->move($directory, $file->getClientOriginalName());
 
+    // when "webkitdirectory" upload was used
+    // otherwise the value will be the same as getClientOriginalName
+    // $file->move($directory, $file->getClientOriginalPath());
+
     // compute a random name and try to guess the extension (more secure)
     $extension = $file->guessExtension();
     if (!$extension) {
@@ -63,9 +67,9 @@ You might calculate the filename in one of the following ways::
     }
     $file->move($directory, rand(1, 99999).'.'.$extension);
 
-Using the original name via ``getClientOriginalName()`` is not safe as it
-could have been manipulated by the end-user. Moreover, it can contain
-characters that are not allowed in file names. You should sanitize the name
+Using the original name via ``getClientOriginalName()`` or ``getClientOriginalPath``
+is not safe as it could have been manipulated by the end-user. Moreover, it can contain
+characters that are not allowed in file names. You should sanitize the value
 before using it directly.
 
 Read :doc:`/controller/upload_file` for an example of how to manage a file