Merge pull request #383 from gsteel/v3/context-parameter

Improve documentation of the `$context` parameter

docs/book/v3/validator-chains.md

@@ -142,3 +142,13 @@ $factory = $container->get(ValidatorChainFactory::class);
 $chain = $factory->fromArray($chainConfiguration);
 $chain->isValid('Some Value');
 ```
+
+## About the `$context` Parameter
+
+Typically, `laminas-validator` is used via [`laminas-inputfilter`](https://docs.laminas.dev/laminas-inputfilter/) which is often, in turn, used via [`laminas-form`](https://docs.laminas.dev/laminas-form/).
+Some validators accept a second parameter to the `isValid()` method that contains the entire payload in an unfiltered and un-validated state.
+This parameter `$context` is normally the entire `$_POST` payload.
+
+`laminas-inputfilter` always passes this parameter to the `isValid` method, but, because it is not part of the `ValidatorInterface` contract, it's documentation has often been overlooked.
+
+`ValidatorChain` accepts this parameter and will pass the context to all composed validators in the chain during validation.

docs/book/v3/validators/explode.md

@@ -48,3 +48,11 @@ $explodeValidator = new Laminas\Validator\Explode([
 $explodeValidator->isValid('a;b'); // returns true
 $explodeValidator->isValid('x;y;z');  // returns false
 ```
+
+## About the `$context` Parameter
+
+The `isValid` implementation in `Explode` accepts a second argument `?array $context = null`.
+
+This argument when used via `laminas-inputfilter` will contain the entire payload, typically `$_POST`.
+
+The context is passed to the composed item validator that checks each element in the given value in case that composed validator needs access to the wider validation context to perform conditional validation.

docs/book/v3/validators/identical.md

@@ -30,6 +30,23 @@ $validator->isValid('goat'); // false
 The validation will only then return `true` when both values are 100% identical.
 In our example, when `$value` is `'donkey'`.
 
+## Relationship to the `$context` Parameter
+
+When `laminas-validator` is used with `laminas-inputfilter`, the entire payload _(Typically `$_POST`)_, is passed as the second argument to the validator as `$context`.
+You can provide a string key as the token and the Identical validator will consult the `$context` parameter when it is available:
+
+```php
+$context = [
+    'first' => 'donkey',
+    'second' => 'goat',
+    'input' => 'cat',
+];
+$validator = new Laminas\Validator\Identical(['token' => 'first');
+
+$validator->isValid($formPayload['input'], $context); // false - 'cat' !== 'donkey'
+$validator->isValid('donkey', $context); // true
+```
+
 ## Identical Objects
 
 `Laminas\Validator\Identical` can validate not only strings, but any other variable

docs/book/v3/writing-validators.md

@@ -225,3 +225,17 @@ the input password failed to meet the validation requirements. If, for example,
 a user were to input the string `#$%` as a password, `isValid()` would cause
 all four validation failure messages to be returned by a subsequent call to
 `getMessages()`.
+
+## Access to the Wider Validation Context
+
+Typically, `laminas-validator` is used via `laminas-inputfilter` which is often, in turn, used via `laminas-form`.
+When validators are used in these contexts, validators are provided with a second argument to the `isValid()` method - an array that represents the entire payload _(Typically `$_POST`)_ in an unfiltered and un-validated state.
+
+Your custom validator can use this context to perform conditional validation by amending the signature of your `isValid` method to:
+
+```php
+public function isValid(mixed $value, ?array $context = null): bool
+{
+    // ... validation logic
+}
+```