diff --git a/docs/book/v3/validator-chains.md b/docs/book/v3/validator-chains.md index e6948a70..8be9c057 100644 --- a/docs/book/v3/validator-chains.md +++ b/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. diff --git a/docs/book/v3/validators/explode.md b/docs/book/v3/validators/explode.md index 8a588341..9e3f90e7 100644 --- a/docs/book/v3/validators/explode.md +++ b/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. diff --git a/docs/book/v3/validators/identical.md b/docs/book/v3/validators/identical.md index 5364d09f..ae347534 100644 --- a/docs/book/v3/validators/identical.md +++ b/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 diff --git a/docs/book/v3/writing-validators.md b/docs/book/v3/writing-validators.md index 330d8114..f01ff32e 100644 --- a/docs/book/v3/writing-validators.md +++ b/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 +} +```