Improve consumer type inference with InputFilter templates

[gsteel]

Q	A
RFC	yes

Description

Adds a template to InputFilterInterface to define the array shape of filtered values

The plan here is better inference when calling InputFilterInterface::getValues(). It might cause a lot of noise for users because psalm requires a template declaration for all inheritors, that said, it'd be useful to those who care.

Once merged, users will be able to define an input filter such as:

/**
 * @psalm-type ValidPayload = array{
 *   inputA: non-empty-string,
 *   inputB: int,
 *   inputC: DateTimeImmutable,
 * @extends InputFilter<ValidPayload>
 */
final class MyInputFilter extends InputFilter
{
  public function init(): void
  {
    // Set up inputs according to desired constraints…
  }
}

… and psalm will infer the types for whatever comes out of $inputFilter->getValues() such as:

$values = $inputFilter->getValues();

printf('The Date is %s', $values['inputC']->format('Y-m-d'));

As part of wrestling with Psalm on this patch, it's worth mentioning that all input names can now be array-key as opposed to string. This is not really related to the patch but something I had to address because CollectionInputFilter is effectively a nested list, it's actually a requirement to be able to fetch an input with something like $inputFilter->get(1)

This work has also uncovered at least one or two subtle bugs or ambiguous behaviour and fixes an issue where InputFilter::add will attempt to call Input::merge with an InputFilter as an argument

[weierophinney]

Love the fact that you (a) added more tests to cover more scenarios, and (b) added the static analysis classes to validate the templates!

One big request, however: I think it would be fantastic to add some info to the docs about the Psalm shapes, and some examples of how they are used (these could be pulled from the static analysis cases you provide, or even just link to them). This will make it clear that we offer the feature; otherwise, it will only be discoverd by those diving into the source code.

[weierophinney]

Why was this condition added?

[gsteel]

InputFilter::add() accepts InputInterface|InputFilterInterface - The condition was always there, asserting the left side was InputInterface but there was nothing to check the right side was the correct type - There's a test to cover it - effectively, we had the possibility of types smashing together with InputInterface::merge(InputFilterInterface) - I considered changing the original condition to just check the type equality but that would have broken BC - i.e. the existing behaviour would be a replace if the type was an InputFilterInterface

[gsteel]

Added a first stab at documentation @weierophinney

[weierophinney]

Added a first stab at documentation

Perfect!

I'm approving now, but only because I don't fully understand Marco's concern (though your explanation makes sense to me).

[Ocramius]

Thanks @gsteel!