Invokable constraints

[linepogl]

PHP 8.5 is coming soon. I believe that PHPUnit's constraints is a very good use case for the new pipe operator.

The new pipe operator forwards a value to any kind of callable, including invokable objects. If PHPUnit's constraints were invokable, then they could be used with the new pipe operator to directly test some value against a constraint.

I have created a proof-of-concept here: https://github.com/linepogl/should

Example of an invocable constraint:

final class IsEqual extends Constraint
{
    ...

    /**
     * @template A
     * @param A $actual
     * @return A
     */
    #[Override]
    public function __invoke(mixed $actual): mixed
    {
        Assert::assertThat($actual, $this);
        return $actual;
    }

    ...
}

Usage:

$actual |> new IsEqual('test')

Benefits

Readability

Invokable constraints give a syntax similar to expect( $actual )->to... for free.

// (current)
Assert::assertThat(new IsEqual('test'), $actual);

// (proposed)
$actual |> new IsEqual('test');

Static type checking

Since every __invoke method has its own signature, the acceptable types of the $actual value can be statically defined and checked:

$actual = 5;

// (current) 
// The generic signature of `assertThat` does not help static type checkers
// resulting in a run-time TypeError: expected string, got int
Assert::assertThat(new RegularExpression('/test/'), $actual); 

// (proposed)
// A tailored signature for `__invoke` of the constraint `RegularExpression`
// makes it possible to detect the error statically
$actual |> new RegularExpression('/test/');

Static type narrowing

Again the signature of __invoke can be used to pass type narrowing instructions to the static type checker.

// (current) 
// impossible to statically determine what's the type of $actual
Assert::assertThat(new IsString(), $actual); 

// (proposed)
// thanks to the signature of `__invoke`, it's possible to narrow the type of $actual to string, 
$actual |> new IsString();

Simple chaining

Testing a value against multiple constraints can be easy with the proposed syntax

// (proposed)
$actual
|> new IsString()
|> new RegularExpression('/test/');

Minor expectation parameters placement

The minor parameters of an assertion, like delta in the example below, are conceptually part of the expectation. However, the order of the arguments separates them from the expected value:

// (current)
Assert::assertEqualsWithDelta(5, $actual, 0.05);

With the proposed syntax, the minor expectation parameters are nicely grouped with the expected value:

// (proposed)
$actual |> new IsEqualWithDelta(5, 0.05);

[massimilianobraglia]

This would be awesome!

[sebastianbergmann]

I just tried

diff --git a/src/Framework/Constraint/Constraint.php b/src/Framework/Constraint/Constraint.php
index 3a3483e3f0..737f1996cf 100644
--- a/src/Framework/Constraint/Constraint.php
+++ b/src/Framework/Constraint/Constraint.php
@@ -19,6 +19,7 @@
 use function strtolower;
 use function substr;
 use Countable;
+use PHPUnit\Framework\Assert;
 use PHPUnit\Framework\ExpectationFailedException;
 use PHPUnit\Framework\SelfDescribing;
 use PHPUnit\Util\Exporter;
@@ -30,6 +31,20 @@
  */
 abstract class Constraint implements Countable, SelfDescribing
 {
+    /**
+     * @template A
+     *
+     * @param A $actual
+     *
+     * @return A
+     */
+    final public function __invoke(mixed $actual): mixed
+    {
+        Assert::assertThat($actual, $this);
+
+        return $actual;
+    }
+
     /**
      * Evaluates the constraint for parameter $other.
      *

and can confirm that the example shown below works as expected:

<?php declare(strict_types=1);
namespace PHPUnit\TestFixture;

use PHPUnit\Framework\TestCase;

final class InvokableConstraintAndPipeOperatorTest extends TestCase
{
    public function testOne(): void
    {
        $actual = 'string';

        $actual |> $this->isString()
                |> $this->stringContains('string');
    }
}

Although I don't think I'll use this syntax, I do think it should be supported. Thank you for the idea!

Since every __invoke() method has its own signature, the acceptable types of the $actual value can be statically defined and checked

While type safety is very important to me, I think I prefer a single __invoke() method in the abstract Constraint class as shown above. That way, all subtypes of Constraint have an __invoke() method and can be used with the |> operator.

What do you think?

[sebastianbergmann]

@Crell I would love to hear your thoughts on this. Thanks!

[linepogl]

I think I prefer a single __invoke() method in the abstract Constraint class

That's good enough. I wouldn't mark it as final though, in order to leave to possibility open if some constraint wants to go the extra mile.

Thanks!

[sebastianbergmann]

That's good enough. I wouldn't mark it as final though, in order to leave to possibility open if some constraint wants to go the extra mile.

A subclass cannot narrow the parameter type for the $actual parameter from mixed.

[Crell]

I hadn't thought of using pipes this way, but it looks neat!

It might be helpful to have some wrapper utility functions rather than using new each time, but that's optional. (I'm personally used to just always calling self::assertSomething rather than instantiating a constraint myself.)

One limitation is that we do not, yet, have PFA, which would be even nicer. I don't think that blocks us from supporting this now, though. It just may have an even nicer alternative in 8.6, if all goes according to plan.

Oh, this has been merged now...

[sebastianbergmann]

@Crell The example in #6354 (comment) does not have new anymore.