Merge pull request #5508 from kenjis/fix-uploaded-file

docs: improve File Uploading

Author: kenjis

user_guide_src/source/incoming/incomingrequest.rst

@@ -293,8 +293,8 @@ and uses best practices to minimize any security risks.
     $files = $request->getFiles();
 
     // Grab the file by name given in HTML form
-    if ($files->hasFile('uploadedFile')) {
-        $file = $files->getFile('uploadedfile');
+    if ($files->hasFile('userfile')) {
+        $file = $files->getFile('userfile');
 
         // Generate a new secure name
         $name = $file->getRandomName();
@@ -309,12 +309,14 @@ and uses best practices to minimize any security risks.
 
 You can retrieve a single file uploaded on its own, based on the filename given in the HTML file input::
 
-    $file = $request->getFile('uploadedfile');
+    $file = $request->getFile('userfile');
 
 You can retrieve an array of same-named files uploaded as part of a
 multi-file upload, based on the filename given in the HTML file input::
 
-    $files = $request->getFileMultiple('uploadedfile');
+    $files = $request->getFileMultiple('userfile');
+
+.. note:: The files here correspond to ``$_FILES``. Even if a user just clicks submit button of a form and does not upload any file, the file will still exist. You can check that the file was actually uploaded by the ``isValid()`` method in UploadedFile. See :ref:`verify-a-file` for more details.
 
 Content Negotiation
 -------------------

user_guide_src/source/libraries/uploaded_files.rst

@@ -194,6 +194,8 @@ Which would return a simple array like::
         'avatar' => // UploadedFile instance
     ]
 
+.. note:: The UploadedFile instance corresponds to ``$_FILES``. Even if a user just clicks the submit button and does not upload any file, the instance will still exist. You can check that the file was actually uploaded by the ``isValid()`` method in UploadedFile. See :ref:`verify-a-file`.
+
 If you used an array notation for the name, the input would look something like::
 
     <input type="file" name="my-form[details][avatar]" />
@@ -231,7 +233,7 @@ Single File
 If you just need to access a single file, you can use ``getFile()`` to retrieve the file instance directly. This will return an instance of ``CodeIgniter\HTTP\Files\UploadedFile``:
 
 Simplest usage
-^^^^^^^^^^^^^^
+--------------
 
 With the simplest usage, a single file might be submitted like::
 
@@ -242,7 +244,7 @@ Which would return a simple file instance like::
     $file = $this->request->getFile('userfile');
 
 Array notation
-^^^^^^^^^^^^^^
+--------------
 
 If you used an array notation for the name, the input would look something like::
 
@@ -253,7 +255,8 @@ For get the file instance::
     $file = $this->request->getFile('my-form.details.avatar');
 
 Multiple files
-^^^^^^^^^^^^^^
+==============
+
 ::
 
     <input type="file" name="images[]" multiple />
@@ -269,9 +272,10 @@ In controller::
         }
     }
 
-where the **images** is a loop from the form field name
+where the ``images`` is a loop from the form field name.
+
+If there are multiple files with the same name you can use ``getFile()`` to retrieve every file individually.
 
-If there are multiple files with the same name you can use ``getFile()`` to retrieve every file individually::
 In controller::
 
     $file1 = $this->request->getFile('images.0');
@@ -301,7 +305,9 @@ Working With the File
 Once you've retrieved the UploadedFile instance, you can retrieve information about the file in safe ways, as well as
 move the file to a new location.
 
-Verify A File
+.. _verify-a-file:
+
+Verify a File
 =============
 
 You can check that a file was actually uploaded via HTTP with no errors by calling the ``isValid()`` method::