Merge pull request cakephp#5752 from ndm2/dynamic-validation/rule-err…

…or-messages

Document dynamic validation/rule error messages.

en/core-libraries/validation.rst

@@ -140,6 +140,8 @@ full set of validator methods.
 .. versionadded:: 3.2
     Rule building methods were added in 3.2.0
 
+.. _custom-validation-rules:
+
 Using Custom Validation Rules
 -----------------------------
 
@@ -201,8 +203,42 @@ Then ensure that your validation method has the second context parameter. ::
     }
 
 Closures should return boolean true if the validation passes. If it fails,
-return boolean false or for a custom error message return a string.
+return boolean false or for a custom error message return a string, see the
+:ref:`Conditional/Dynamic Error Messages <dynamic_validation_error_messages>`
+section for further details.
+
+.. _dynamic_validation_error_messages:
+
+Conditional/Dynamic Error Messages
+----------------------------------
+
+Validation rule methods, being it :ref:`custom callables <custom-validation-rules>`,
+or :ref:`methods supplied by providers <adding-validation-providers>`, can either
+return a boolean, indicating whether the validation succeeded, or they can return
+a string, which means that the validation failed, and that the returned string
+should be used as the error message.
+
+Possible existing error messages defined via the ``message`` option will be
+overwritten by the ones returned from the validation rule method::
+
+    $validator->add('length', 'custom', [
+        'rule' => function ($value, $context) {
+            if (!$value) {
+                return false;
+            }
 
+            if ($value < 10) {
+                return 'Error message when value is less than 10';
+            }
+
+            if ($value > 20) {
+                return 'Error message when value is greater than 20';
+            }
+
+            return true;
+        },
+        'message' => 'Generic error message used when `false` is returned'
+    ]);
 
 Conditional Validation
 ----------------------
@@ -296,6 +332,8 @@ a specific rule has failed, you can set the ``last`` option to ``true``::
 If the minLength rule fails in the example above, the maxLength rule will not be
 run.
 
+.. _adding-validation-providers:
+
 Adding Validation Providers
 ---------------------------
 

en/orm/validation.rst

@@ -290,6 +290,8 @@ before entities are persisted. Some example domain rules are:
 
 Domain rules are checked when calling the Table ``save()`` and ``delete()`` methods.
 
+.. _creating-a-rules-checker:
+
 Creating a Rules Checker
 ------------------------
 
@@ -474,6 +476,46 @@ You may want to conditionally apply rules based on entity data::
         return false;
     }, 'userExists');
 
+Conditional/Dynamic Error Messages
+----------------------------------
+
+Rules, being it :ref:`custom callables <creating-a-rules-checker>`, or
+:ref:`rule objects <creating-custom-rule-objects>`, can either return a boolean, indicating
+whether they passed, or they can return a string, which means that the rule did not pass,
+and that the returned string should be used as the error message.
+
+Possible existing error messages defined via the ``message`` option will be overwritten
+by the ones returned from the rule::
+
+    $rules->add(
+        function ($entity, $options) {
+            if (!$entity->length) {
+                return false;
+            }
+
+            if ($entity->length < 10) {
+                return 'Error message when value is less than 10';
+            }
+
+            if ($entity->length > 20) {
+                return 'Error message when value is greater than 20';
+            }
+
+            return true;
+        },
+        'ruleName',
+        [
+            'errorField' => 'length',
+            'message' => 'Generic error message used when `false` is returned'
+        ]
+     );
+
+.. note::
+
+    Note that in order for the returned message to be actually used, you *must* also supply the
+    ``errorField`` option, otherwise the rule will just silently fail to pass, ie without an
+    error message being set on the entity!
+
 Creating Custom re-usable Rules
 -------------------------------
 
@@ -492,6 +534,8 @@ You may want to re-use custom domain rules. You can do so by creating your own i
 
 See the core rules for examples on how to create such rules.
 
+.. _creating-custom-rule-objects:
+
 Creating Custom Rule Objects
 ----------------------------