docs: add changelog and upgrade

Author: kenjis

user_guide_src/source/changelogs/v4.4.4.rst

@@ -14,6 +14,13 @@ Release Date: Unreleased
 BREAKING
 ********
 
+Validation with Dot Array Syntax
+================================
+
+A validation rule with the wildcard ``*`` now validates only data in correct
+dimensions as "dot array syntax".
+See :ref:`Upgrading <upgrade-444-validation-with-dot-array-syntax>` for details.
+
 ***************
 Message Changes
 ***************

user_guide_src/source/installation/upgrade_444.rst

@@ -20,6 +20,25 @@ Mandatory File Changes
 Breaking Changes
 ****************
 
+.. _upgrade-444-validation-with-dot-array-syntax:
+
+Validation with Dot Array Syntax
+================================
+
+If you are using :ref:`dot array syntax <validation-dot-array-syntax>` in validation
+rules, a bug where ``*`` would validate data in incorrect dimensions has been fixed.
+
+In previous versions, the rule key ``contacts.*.name`` captured data with any
+level like ``contacts.*.name``, ``contacts.*.*.name``, ``contacts.*.*.*.name``,
+etc., incorrectly.
+
+The following code explains details:
+
+.. literalinclude:: upgrade_444/001.php
+   :lines: 2-
+
+If you have code that depends on the bug, fix the the rule key.
+
 *********************
 Breaking Enhancements
 *********************

user_guide_src/source/installation/upgrade_444/001.php

@@ -0,0 +1,38 @@
+<?php
+
+use Config\Services;
+
+$validation = Services::validation();
+
+$data = [
+    'contacts' => [
+        'name' => 'Joe Smith',
+        'just' => [
+            'friends' => [
+                ['name' => 'SATO Taro'],
+                ['name' => 'Li Ming'],
+                ['name' => 'Heinz Müller'],
+            ],
+        ],
+    ],
+];
+
+$validation->setRules(
+    ['contacts.*.name' => 'required|max_length[8]']
+);
+
+$validation->run($data); // false
+
+d($validation->getErrors());
+/*
+ Before: Captured `contacts.*.*.*.name` incorrectly.
+ [
+   contacts.just.friends.0.name => "The contacts.*.name field cannot exceed 8 characters in length.",
+   contacts.just.friends.2.name => "The contacts.*.name field cannot exceed 8 characters in length.",
+ ]
+
+ After: Captures no data for `contacts.*.name`.
+ [
+   contacts.*.name => string (38) "The contacts.*.name field is required.",
+ ]
+*/

user_guide_src/source/libraries/validation.rst

@@ -314,6 +314,8 @@ To give a labeled error message you can set up as:
 .. note:: ``setRules()`` will overwrite any rules that were set previously. To add more than one
     rule to an existing set of rules, use ``setRule()`` multiple times.
 
+.. _validation-dot-array-syntax:
+
 Setting Rules for Array Data
 ============================
 
@@ -328,6 +330,10 @@ You can use the ``*`` wildcard symbol to match any one level of the array:
 .. literalinclude:: validation/010.php
    :lines: 2-
 
+.. note:: Prior to v4.4.4, due to a bug, the wildcard ``*`` validated data in incorrect
+    dimensions. See :ref:`Upgrading <upgrade-444-validation-with-dot-array-syntax>`
+    for details.
+
 "dot array syntax" can also be useful when you have single dimension array data.
 For example, data returned by multi select dropdown: