Merge pull request #8876 from kenjis/docs-improve-file-upload-validation

kenjis · web-flow · commit 2977b0291509 · 2024-05-10T15:34:55.000+09:00
docs: improve file upload validation
diff --git a/user_guide_src/source/libraries/uploaded_files.rst b/user_guide_src/source/libraries/uploaded_files.rst
@@ -2,8 +2,10 @@
 Working with Uploaded Files
 ###########################
 
-CodeIgniter makes working with files uploaded through a form much simpler and more secure than using PHP's ``$_FILES``
-array directly. This extends the :doc:`File class </libraries/files>` and thus gains all of the features of that class.
+CodeIgniter makes working with files uploaded through a form much simpler and
+more secure than using PHP's ``$_FILES`` array directly. This extends the
+:doc:`File class </libraries/files>` and thus gains all of the features of that
+class.
 
 .. note:: This is not the same as the File Uploading class in CodeIgniter 3.
     This provides a raw interface to the uploaded files with a few small features.
@@ -12,9 +14,11 @@ array directly. This extends the :doc:`File class </libraries/files>` and thus g
     :local:
     :depth: 2
 
-***********
-The Process
-***********
+.. _file-upload-form-tutorial:
+
+*************************
+File Upload Form Tutorial
+*************************
 
 Uploading a file involves the following general process:
 
@@ -33,21 +37,23 @@ Creating the Upload Form
 ========================
 
 Using a text editor, create a form called **upload_form.php**. In it, place
-this code and save it to your **app/Views/** directory:
+this code and save it to your **app/Views** directory:
 
 .. literalinclude:: uploaded_files/001.php
 
 You'll notice we are using a form helper to create the opening form tag.
 File uploads require a multipart form, so the helper creates the proper
-syntax for you. You'll also notice we have an ``$errors`` variable. This is
+syntax for you.
+
+You'll also notice we have an ``$errors`` variable. This is
 so we can show error messages in the event the user does something
 wrong.
 
 The Success Page
 ================
 
 Using a text editor, create a form called **upload_success.php**. In it,
-place this code and save it to your **app/Views/** directory::
+place this code and save it to your **app/Views** directory::
 
     <!DOCTYPE html>
     <html lang="en">
@@ -73,13 +79,23 @@ The Controller
 ==============
 
 Using a text editor, create a controller called **Upload.php**. In it, place
-this code and save it to your **app/Controllers/** directory:
+this code and save it to your **app/Controllers** directory:
 
 .. literalinclude:: uploaded_files/002.php
 
-.. note:: Since the value of a file upload HTML field doesn't exist, and is stored in the ``$_FILES`` global,
-    only :ref:`rules-for-file-uploads` can be used to validate upload file with :doc:`validation`.
-    The rule ``required`` also can't be used, so use ``uploaded`` instead.
+Since the value of a file upload HTML field doesn't exist, and is stored in the
+``$_FILES`` global, only :ref:`rules-for-file-uploads` can be used to validate
+upload file with :doc:`validation`.
+
+The rule ``required`` cannot be used either, so if the file is required, use
+the rule ``uploaded`` instead.
+
+Note that an empty array (``[]``) is passed as the first argument to
+``$this->validateData()``. It is because the file validation rules get the data
+for the uploaded file directly from the Request object.
+
+If the form has fields other than file upload, pass the field data as the first
+argument.
 
 The Routes
 ==========
diff --git a/user_guide_src/source/libraries/validation.rst b/user_guide_src/source/libraries/validation.rst
@@ -885,6 +885,8 @@ Available Rules
 .. literalinclude:: validation/038.php
    :lines: 2-
 
+.. _rules-for-general-use:
+
 Rules for General Use
 =====================
 
@@ -1044,9 +1046,10 @@ file validation.
     files. Therefore, adding any general rules, like ``permit_empty``, to file
     validation rules array or string, the file validation will not work correctly.
 
-Since the value of a file upload HTML field doesn't exist, and is stored in the ``$_FILES`` global, the name of the input field will
-need to be used twice. Once to specify the field name as you would for any other rule, but again as the first parameter of all
-file upload related rules::
+Since the value of a file upload HTML field doesn't exist, and is stored in the
+``$_FILES`` global, the name of the input field will need to be used twice. Once
+to specify the field name as you would for any other rule, but again as the first
+parameter of all file upload related rules::
 
     // In the HTML
     <input type="file" name="avatar">
@@ -1056,6 +1059,8 @@ file upload related rules::
         'avatar' => 'uploaded[avatar]|max_size[avatar,1024]',
     ]);
 
+See also :ref:`file-upload-form-tutorial`.
+
 ======================= ========== ============================================= ===================================================
 Rule                    Parameter  Description                                   Example
 ======================= ========== ============================================= ===================================================
