[RFC] Aggregate Validation

[gsteel]

Feature Request

It's often necessary to validate more than one field at a time, for example to make sure that the input for 2 fields is identical (amongst many other use-cases for conditional validation).

Normally, you'd attach a callback validator to the field you wish to fail but this has some drawbacks:

• At the time the callback is called, you can't be sure that both fields are initially valid because the order of validation (fields) is not guaranteed. This means that you have to perform redundant, basic validation of both fields again before you can get on with the main purpose of the callback. This is a bigger problem, the more fields are involved with the aggregate validation.
• Using callbacks like this gets messy - if you want to correctly assign the validation failure to a specific input, you need to pass in references to whatever you haven't bound to - i.e. Bind the callback to nothing (default), the InputFilter ($this), the validator instance, a single input etc - each has its own drawbacks.
• Having aggregate validation fail multiple fields is difficult - the only way you can add intelligible error messages is via binding the callback to the validator instance, putting other fields out of reach.

Proposal

Implement a way to perform aggregate validation, after all fields have been filtered and validated.

Whether aggregate validation occurs will be dependent on whether the user wants all fields to first be individually valid or not.

Aggregate validation will only be usable via a public method on InputFilter such as attachAggregateValidator(callable $validator, bool $requireValidPayload) where the callable will be well defined.

It must also be easy for the user to indicate:

• which fields should be considered as failed
• add descriptive error messages to each failing field
• ensure that error messages are appended to any existing errors for the relevant fields.

I don't envisage adding this to the array-based factory spec for input filters.

[gsteel]

Pinging @laminas/technical-steering-committee for input…

[Ocramius]

@gsteel I understand the problem statement, but I don't understand the proposed solution.

Could you perhaps pseudo-code it?

[gsteel]

Thanks @Ocramius - Hopefully this explains a potential solution 👍

$requireValidPayload = false;

$inputFilter = new SomeInputFilter();
$inputFilter->attachAggregregateValidation($maybeCallableOrValidator, $requireValidPayload);
$inputFilter->setData($payload);

// In this case aggregate validation will run whether $payload is valid or not
// $requireValidPayload is analogous to `break_chain_on_failure`
if (! $inputFilter->isValid()) {
    $inputFilter->getMessages();
}

$inputFilter = new SomeInputFilter();
$inputFilter->attachAggregregateValidation($maybeCallableOrValidator, true);
$inputFilter->setData($payload);
// In this case aggregate validation will only run once all individual fields are considered valid
if (! $inputFilter->isValid()) {
    $inputFilter->getMessages();
}

I think that the validation callable would probably need a signature such as:

Closure(InputFilter $inputs, bool $isValid): bool

Most information required can be retrieved from the input filter and $isValid makes it uneccessary to call InputFilter::isValid() again from the closure context if the validation needs this information.

Sticking to ValidatorInterface as opposed to callable here is not a good idea IMO because it would mean forcing users to write custom validators for an array input.

Perhaps introducing an interface specifically for this aggregate validation would bring better types at the expense of distancing the validation logic from the only place it is likely to be used (Inside an input filter)

I would expect to append a custom validator to the chain for every input so that there is a reliable way of appending failure messages to each input's message stack.

This would all be a lot simpler if we had stateless validators and result objects, but we don't so implementation would need to be @internal where possible.

Example custom input filter:

final class MyInputFilter extends InputFilter
{
    public function init(): void
    {
        $this->add([
            'validators' => [
                ['name' => NotEmpty::class],
                ['name' => SomePasswordRules::class],
            ],
        ], 'password');

        $this->add([
            'validators' => [
                ['name' => NotEmpty::class],
                ['name' => SomePasswordRules::class],
            ],
        ], 'password-confirmation');

        $this->attachAggregateValidation($this->aggregateValidator(), true);
    }

    /** @return Closure(InputFilter, bool): bool */
    private function aggregateValidator(): Closure
    {
        return function (InputFilter $inputs, bool $_notRequired): bool {
            if ($inputs->getValue('password') === $inputs->getValue('password-confirmation')) {
                return true;
            }

            $confirmation = $inputs->get('password-confirmation');
            $this->appendErrorMessage(
                $confirmation,
                'someUniqueErrorKey',
                'The passwords don’t match',
            );

            return false;
        };
    }
}