Merge pull request #7685 from kenjis/docs-in-model-validation

docs: improve In-model Validation

Author: kenjis

user_guide_src/source/helpers/form_helper.rst

@@ -536,6 +536,10 @@ The following functions are available:
     The returned array is the same as ``Validation::getErrors()``.
     See :ref:`Validation <validation-redirect-and-validation-errors>` for details.
 
+    .. note:: This function does not work with :ref:`in-model-validation`. If you
+        want to get the validation errors in model validation, see
+        :ref:`model-getting-validation-errors`.
+
     Example::
 
         <?php $errors = validation_errors(); ?>
@@ -555,6 +559,10 @@ The following functions are available:
 
     This function uses :php:func:`validation_errors()` internally.
 
+    .. note:: This function does not work with :ref:`in-model-validation`. If you
+        want to get the validation errors in model validation, see
+        :ref:`model-getting-validation-errors`.
+
     Example::
 
         <?= validation_list_errors() ?>
@@ -575,6 +583,10 @@ The following functions are available:
 
     This function uses :php:func:`validation_errors()` internally.
 
+    .. note:: This function does not work with :ref:`in-model-validation`. If you
+        want to get the validation errors in model validation, see
+        :ref:`model-getting-validation-errors`.
+
     Example::
 
         <?= validation_show_error('username') ?>

user_guide_src/source/models/model.rst

@@ -4,7 +4,7 @@ Using CodeIgniter's Model
 
 .. contents::
     :local:
-    :depth: 2
+    :depth: 3
 
 Models
 ******
@@ -456,6 +456,8 @@ Cleans out the database table by permanently removing all rows that have 'delete
 
 .. literalinclude:: model/026.php
 
+.. _in-model-validation:
+
 In-Model Validation
 ===================
 
@@ -473,11 +475,19 @@ prior to saving to the database with the ``insert()``, ``update()``, or ``save()
     If you want to check required fields, you can change the behavior by configuration.
     See :ref:`clean-validation-rules` for details.
 
+Setting Validation Rules
+------------------------
+
 The first step is to fill out the ``$validationRules`` class property with the fields and rules that should
 be applied. If you have custom error message that you want to use, place them in the ``$validationMessages`` array:
 
 .. literalinclude:: model/027.php
 
+If you'd rather organize your rules and error messages within the Validation configuration file, you can do that
+and simply set ``$validationRules`` to the name of the validation rule group you created:
+
+.. literalinclude:: model/034.php
+
 The other way to set the validation rules to fields by functions,
 
 .. php:namespace:: CodeIgniter
@@ -528,8 +538,18 @@ The other way to set the validation message to fields by functions,
 
     .. literalinclude:: model/031.php
 
+Getting Validation Result
+-------------------------
+
 Now, whenever you call the ``insert()``, ``update()``, or ``save()`` methods, the data will be validated. If it fails,
-the model will return boolean **false**. You can use the ``errors()`` method to retrieve the validation errors:
+the model will return boolean **false**.
+
+.. _model-getting-validation-errors:
+
+Getting Validation Errors
+-------------------------
+
+You can use the ``errors()`` method to retrieve the validation errors:
 
 .. literalinclude:: model/032.php
 
@@ -538,11 +558,6 @@ errors at the top of the form, or to display them individually:
 
 .. literalinclude:: model/033.php
 
-If you'd rather organize your rules and error messages within the Validation configuration file, you can do that
-and simply set ``$validationRules`` to the name of the validation rule group you created:
-
-.. literalinclude:: model/034.php
-
 Retrieving Validation Rules
 ---------------------------
 
@@ -572,6 +587,9 @@ replaced by the **value** of the matched incoming field. An example should clari
 
 .. literalinclude:: model/038.php
 
+.. note:: Since v4.3.5, you must set the validation rules for the placeholder
+    field (``id``).
+
 In this set of rules, it states that the email address should be unique in the database, except for the row
 that has an id matching the placeholder's value. Assuming that the form POST data had the following:
 
@@ -583,6 +601,9 @@ then the ``{id}`` placeholder would be replaced with the number **4**, giving th
 
 So it will ignore the row in the database that has ``id=4`` when it verifies the email is unique.
 
+.. note:: Since v4.3.5, if the placeholder (``id``) value does not pass the
+    validation, the placeholder would not be replaced.
+
 This can also be used to create more dynamic rules at runtime, as long as you take care that any dynamic
 keys passed in don't conflict with your form data.
 

user_guide_src/source/models/model/027.php

@@ -7,10 +7,10 @@
 class UserModel extends Model
 {
     protected $validationRules = [
-        'username'     => 'required|alpha_numeric_space|min_length[3]',
-        'email'        => 'required|valid_email|is_unique[users.email]',
-        'password'     => 'required|min_length[8]',
-        'pass_confirm' => 'required_with[password]|matches[password]',
+        'username'     => 'required|max_length[30]|alpha_numeric_space|min_length[3]',
+        'email'        => 'required|max_length[254]|valid_email|is_unique[users.email]',
+        'password'     => 'required|max_length[255]|min_length[8]',
+        'pass_confirm' => 'required_with[password]|max_length[255]|matches[password]',
     ];
     protected $validationMessages = [
         'email' => [

user_guide_src/source/models/model/028.php

@@ -1,6 +1,6 @@
 <?php
 
 $fieldName  = 'username';
-$fieldRules = 'required|alpha_numeric_space|min_length[3]';
+$fieldRules = 'required|max_length[30]|alpha_numeric_space|min_length[3]';
 
 $model->setValidationRule($fieldName, $fieldRules);

user_guide_src/source/models/model/029.php

@@ -1,9 +1,9 @@
 <?php
 
 $validationRules = [
-    'username' => 'required|alpha_numeric_space|min_length[3]',
+    'username' => 'required|max_length[30]|alpha_numeric_space|min_length[3]',
     'email'    => [
-        'rules'  => 'required|valid_email|is_unique[users.email]',
+        'rules'  => 'required|max_length[254]|valid_email|is_unique[users.email]',
         'errors' => [
             'required' => 'We really need your email.',
         ],

user_guide_src/source/models/model/038.php

@@ -7,6 +7,7 @@
 class MyModel extends Model
 {
     protected $validationRules = [
-        'email' => 'required|valid_email|is_unique[users.email,id,{id}]',
+        'id'    => 'max_length[19]|is_natural_no_zero',
+        'email' => 'required|max_length[254]|valid_email|is_unique[users.email,id,{id}]',
     ];
 }

user_guide_src/source/models/model/040.php

@@ -7,6 +7,7 @@
 class MyModel extends Model
 {
     protected $validationRules = [
-        'email' => 'required|valid_email|is_unique[users.email,id,4]',
+        'id'    => 'max_length[19]|is_natural_no_zero',
+        'email' => 'required|max_length[254]|valid_email|is_unique[users.email,id,4]',
     ];
 }