Update English documentation to match current API (2.0.0–2.5.2)

Author: WarLikeLaux

docs/guide/en/README.md

@@ -11,6 +11,7 @@
 
 - [Built-in rules](built-in-rules.md)
   - [Callback](built-in-rules-callback.md)
+  - [Compare](built-in-rules-compare.md)
   - [Composite](built-in-rules-composite.md)
   - [Each](built-in-rules-each.md)
   - [Nested](built-in-rules-nested.md)

docs/guide/en/built-in-rules-compare.md

@@ -1,5 +1,46 @@
 # `Compare` - comparing validated value with target value
 
+The `Compare` rule and its shortcut classes validate a value by comparing it with a target value or another property.
+
+Available shortcut classes:
+
+- `Equal` (`==`)
+- `NotEqual` (`!=`)
+- `GreaterThan` (`>`)
+- `GreaterThanOrEqual` (`>=`)
+- `LessThan` (`<`)
+- `LessThanOrEqual` (`<=`)
+
+## Comparison types
+
+The `type` parameter controls how values are compared:
+
+- `CompareType::NUMBER` — values are compared as numbers (default).
+- `CompareType::STRING` — values are compared as strings, byte by byte.
+- `CompareType::ORIGINAL` — values are compared as-is, without type casting. Required for `DateTime` objects.
+
+## Comparing with a target value
+
+```php
+use Yiisoft\Validator\Rule\GreaterThanOrEqual;
+
+$rules = [
+    'age' => new GreaterThanOrEqual(18),
+];
+```
+
+## Comparing with another property
+
+Use the `targetProperty` parameter to compare against another property in the same data set:
+
+```php
+use Yiisoft\Validator\Rule\Equal;
+
+$rules = [
+    'password_repeat' => new Equal(targetProperty: 'password'),
+];
+```
+
 ## Using with `DateTime` objects
 
 ### Basic usage
@@ -17,11 +58,11 @@ $rules = [
 ### Dynamic range
 
 ```php
+use DateInterval;
 use DateTime;
-use Yiisoft\Validator\Rule\Callback;
 use Yiisoft\Validator\Rule\CompareType;
-use Yiisoft\Validator\Rule\GreaterThanOrEqual;
-use Yiisoft\Validator\Rule\LessThanOrEqual;
+use Yiisoft\Validator\Rule\GreaterThan;
+use Yiisoft\Validator\Rule\LessThan;
 
 $rules = [
     'shipping_datetime' => [
@@ -34,7 +75,7 @@ $rules = [
             (new DateTime('now'))
                 ->add(DateInterval::createFromDateString('1 week')),
             type: CompareType::ORIGINAL,
-        ),        
+        ),
     ],
 ];
 ```

docs/guide/en/built-in-rules-composite.md

@@ -59,10 +59,10 @@ final class CoordinatesRuleSet extends Composite
     public function getRules(): array
     {
         return [
-            new Nested(
+            new Nested([
                 'latitude' => new Number(min: -90, max: 90),
                 'longitude' => new Number(min: -90, max: 90),
-            ),
+            ]),
         ];
     }
 }

docs/guide/en/built-in-rules-each.md

@@ -30,7 +30,37 @@ $rules = [
 ];
 ```
 
-Validated data items are not limited to only "simple" values - `Each` can be used both within a `Nested` and contain
+## Stopping on first error
+
+By default, `Each` validates all items in the set and collects all errors. To stop validation at the first item
+that produces an error, use the `stopOnError` parameter:
+
+```php
+use Yiisoft\Validator\Rule\Each;
+use Yiisoft\Validator\Rule\Integer;
+
+new Each(
+    rules: [new Integer(min: 0, max: 255)],
+    stopOnError: true,
+);
+```
+
+## Accessing the current key
+
+During validation of each item, the current iteration key is available through the validation context
+parameter `Each::PARAMETER_EACH_KEY`. This can be useful in `when` callbacks or custom rule handlers:
+
+```php
+use Yiisoft\Validator\Rule\Each;
+use Yiisoft\Validator\ValidationContext;
+
+// Inside a when callback or custom rule handler:
+$currentKey = $context->getParameter(Each::PARAMETER_EACH_KEY);
+```
+
+## Using with `Nested`
+
+Validated data items are not limited to only "simple" values — `Each` can be used both within a `Nested` and contain
 `Nested` rule covering one-to-many and many-to-many relations:
 
 ```php
@@ -48,10 +78,10 @@ $rule = new Nested([
                         'x' => [new Number(min: -10, max: 10)],
                         'y' => [new Number(min: -10, max: 10)],
                     ]),
-                    'rgb' => new Each([
+                    'rgb' => [
                         new Count(3),
-                        new Number(min: 0, max: 255),
-                    ]),
+                        new Each([new Number(min: 0, max: 255)]),
+                    ],
                 ]),
             ]),
         ]),

docs/guide/en/built-in-rules-nested.md

@@ -388,6 +388,44 @@ attributes] section.
 - For more information about possible data / rules combinations passed for validation, refer to the [Using validator] 
 section. 
 
+### Conditional validation within nested structures
+
+When using `when` callbacks inside `Nested`, the validation context provides access to sibling properties — other
+properties at the same nesting level. Use `$context->getDataSet()->getPropertyValue()` to read them.
+
+For example, to require `content` only when `isEnabled` is `true`:
+
+```php
+use Yiisoft\Validator\Rule\BooleanValue;
+use Yiisoft\Validator\Rule\Nested;
+use Yiisoft\Validator\Rule\Required;
+use Yiisoft\Validator\ValidationContext;
+use Yiisoft\Validator\Validator;
+
+$data = [
+    'push' => [
+        'isEnabled' => true,
+        'content' => null,
+    ],
+];
+$rules = new Nested([
+    'push' => new Nested([
+        'isEnabled' => [new BooleanValue()],
+        'content' => [
+            new Required(
+                when: static function (mixed $value, ValidationContext $context): bool {
+                    return (bool) $context->getDataSet()->getPropertyValue('isEnabled');
+                },
+            ),
+        ],
+    ]),
+]);
+$result = (new Validator())->validate($data, $rules);
+```
+
+This works at any depth, including when combined with `Each`. For more details and examples, see the
+[Conditional validation] guide.
+
 ### Using keys containing separator / shortcut
 
 If a key contains the separator (`.`), or `Each` shortcut (`*`), it must be escaped with backslash (`\`) in
@@ -462,5 +500,6 @@ $data = [
 [Result]: result.md
 [Basic usage]: #basic-usage-one-to-one-relation
 [JSFiddle]: https://jsfiddle.net/fys8uadr/
+[Conditional validation]: conditional-validation.md
 [Configuring rules via PHP attributes]: configuring-rules-via-php-attributes.md
 [Using validator]: using-validator.md

docs/guide/en/built-in-rules.md

@@ -20,11 +20,12 @@ Here is a list of all available built-in rules, divided by category.
 - [Ip](../../../src/Rule/Ip.php)
 - [Json](../../../src/Rule/Json.php)
 - [Url](../../../src/Rule/Url.php)
+- [Uuid](../../../src/Rule/Uuid.php)
 
 ### Boolean rules
 
-- [Boolean](../../../src/Rule/BooleanValue.php)
-- [IsTrue](../../../src/Rule/TrueValue.php)
+- [BooleanValue](../../../src/Rule/BooleanValue.php)
+- [TrueValue](../../../src/Rule/TrueValue.php)
 
 ### Number rules
 

docs/guide/en/conditional-validation.md

@@ -266,6 +266,83 @@ $rules = [
 $result = (new Validator())->validate($data, $rules);
 ```
 
+### `when` within nested structures
+
+`$context->getDataSet()->getPropertyValue()` also works within nested validation, giving access to sibling properties
+at the same nesting level.
+
+In this example `content` is only required when its sibling property `isEnabled` is `true`:
+
+```php
+use Yiisoft\Validator\Rule\BooleanValue;
+use Yiisoft\Validator\Rule\Nested;
+use Yiisoft\Validator\Rule\Required;
+use Yiisoft\Validator\ValidationContext;
+use Yiisoft\Validator\Validator;
+
+$data = [
+    'push' => [
+        'isEnabled' => true,
+        'content' => null,
+    ],
+];
+$rules = new Nested([
+    'push' => new Nested([
+        'isEnabled' => [new BooleanValue()],
+        'content' => [
+            new Required(
+                when: static function (mixed $value, ValidationContext $context): bool {
+                    return (bool) $context->getDataSet()->getPropertyValue('isEnabled');
+                },
+            ),
+        ],
+    ]),
+]);
+$result = (new Validator())->validate($data, $rules);
+```
+
+Since `isEnabled` is `true`, the `Required` rule is applied and `content` fails validation because it is `null`.
+Setting `isEnabled` to `false` would skip the `Required` rule entirely.
+
+This approach works at any depth, including inside `Each`:
+
+```php
+use Yiisoft\Validator\Rule\BooleanValue;
+use Yiisoft\Validator\Rule\Each;
+use Yiisoft\Validator\Rule\Nested;
+use Yiisoft\Validator\Rule\Required;
+use Yiisoft\Validator\ValidationContext;
+use Yiisoft\Validator\Validator;
+
+$data = [
+    'tasks' => [
+        [
+            'push' => [
+                'isEnabled' => false,
+                'content' => null,
+            ],
+        ],
+    ],
+];
+$rules = new Nested([
+    'tasks' => new Each(
+        new Nested([
+            'push' => new Nested([
+                'isEnabled' => [new BooleanValue()],
+                'content' => [
+                    new Required(
+                        when: static function (mixed $value, ValidationContext $context): bool {
+                            return (bool) $context->getDataSet()->getPropertyValue('isEnabled');
+                        },
+                    ),
+                ],
+            ]),
+        ]),
+    ),
+]);
+$result = (new Validator())->validate($data, $rules);
+```
+
 As an alternative to functions, callable classes can be used instead. This approach has the advantage of code reusability.
 See the [Skip on empty] section for an example.
 

docs/guide/en/configuring-rules-via-php-attributes.md

@@ -71,8 +71,6 @@ final class User
 }
 ```
 
-> **Note:** [readonly properties] are supported only starting from PHP 8.1.
-
 Error messages may include `{property}` placeholder that is replaced with the name of the property. To capitalize the 
 first letter, you can use the `{Property}` placeholder. If you would like the name to be replaced with a custom value, 
 you can specify it using the `Label` attribute:
@@ -91,8 +89,6 @@ final class User
 }
 ```
 
-> **Note:** [readonly properties] are supported only starting from PHP 8.1.
-
 ## Configuring for multiple entities / models with relations
 
 An example of rule set for a blog post configured via arrays only:
@@ -150,7 +146,6 @@ final class Post
     #[Nested]
     public Author|null $author = null;
 
-    // Passing instances is available only since PHP 8.1.
     #[Each(new Nested(File::class))]
     public array $files = [];
 
@@ -330,15 +325,9 @@ final class Yaml implements RuleInterface
 
 ## Limitations and workarounds
 
-### Instances
-
-Passing instances in the scope of attributes is only possible as of PHP 8.1. This means using attributes for complex
-rules such as `Composite`, `Each` and `Nested` or rules that take instances as arguments, can be problematic with PHP 8.0.
-
-The first workaround is to upgrade to PHP 8.1 - this is fairly simple since it is a minor version. Tools like 
-[Rector] can ease the process of upgrading the code base by automating routine tasks.
+### Alternative approaches for complex rules
 
-If this is not an option, you can use other ways of providing rules, such as rule providers:
+For complex rules involving relations (`Nested`, `Each`), you can use rule providers as an alternative to attributes:
 
 ```php
 use Yiisoft\Validator\Rule\Integer;
@@ -452,6 +441,15 @@ method for validation - use a `Callback` rule with [method reference]. Otherwise
 - Use `Composite` or rules provider described in the [Instances] section.
 - Create a [custom rule].
 
+## Combining attributes with `RulesProviderInterface`
+
+When a data object has rules declared via PHP attributes and also implements `RulesProviderInterface`, rules from both
+sources are merged. Rules from PHP attributes are applied first, followed by rules from `getRules()`. If the same
+property has rules in both sources, they are combined.
+
+> **Note:** This merging only applies when the object is passed as the data (first argument of `validate()`). When
+> passed as the rules argument (second argument), only `getRules()` is used — see [Using validator] for details.
+
 ## Using rules
 
 Well, the rules are configured. What's next? We can either:
@@ -565,7 +563,7 @@ $dataSet = new ObjectDataSet(
 $result = (new Validator())->validate($dataSet);
 ```
 
-Some edge cases, like skipping DTO's static properties, require using of `AttributeRulesProvider`. After initializing it 
+Some edge cases, like skipping DTO's static properties, require using of `AttributesRulesProvider`. After initializing it 
 can be passed for validation right away - no need to extract rules manually beforehand.
 
 ```php
@@ -625,6 +623,7 @@ $options = RulesDumper::asArray($rules);
 [Rector]: https://github.com/rectorphp/rector
 [when]: conditional-validation.md#when
 [conditional validation]: conditional-validation.md
-[Instances]: #instances
+[Instances]: #alternative-approaches-for-complex-rules
+[Using validator]: using-validator.md
 [custom rule]: creating-custom-rules.md
 [method reference]: built-in-rules-callback.md#for-property