Laravel 9 introduced a new way to create custom validation rules: invokable rules. It allows you to write a custom validation rule with only one method: __invoke.

Here's a simple example:

namespace App\Rules;
 
use Closure;
use Illuminate\Contracts\Validation\InvokableRule;
 
class UppercaseRule implements InvokableRule
{
    public function __invoke(string $attribute, mixed $value, Closure $fail): void
    {
        if (strtoupper($value) !== $value) {
            $fail('The :attribute must be uppercase.');
        }
    }
}

If you want the rule to fail, your rule should execute the passed $fail closure and give it a good validation error message.

This way of writing custom validation rules will become the default in Laravel 10. (If you're writing your validation classes using the older syntax, no worries, that will still be supported in L10).

When I wrote my first invokable, I was figuring out how to test them. I came up with a nice solution (hat tip to Oliver Nybroe for pointing me in the right direction).

My preferred testing framework these days is Pest. In Pest, there is a way to write custom expectations. If you don't have experience with testing, Pest, or custom expectations, check out my course Testing Laravel, where you'll learn all this from scratch.

Here's the custom expectation I came up with:

expect()->extend('toPassWith', function(mixed $value) {
    $rule = $this->value;

    if (! $rule instanceof InvokableRule) {
        throw new Exception('Value is not an invokable rule');
    }

    $passed = true;

    $fail = function() use (&$passed) {
        $passed = false;
    };

    $rule('attribute', $value, $fail);

    expect($passed)->toBeTrue();
});

In this custom expectation, we'll invoke our rule and pass our own $fail closure to it. Using that $passed variable, we're going to detect if $fail was executed. Notice that &$passed? Here we pass the $passed variable by reference, so when it changes inside the closure, it will also change in our custom expectation.

Using this custom expectation, testing custom rules becomes easy. Let's see it in action.

it('will only accept fully uppercased values', function() {
    $rule = new UppercaseRule();

    expect($rule)->toPassWith('HELLO');

    // using not() you can test the inverse
    expect($rule)->not()->toPassWith('hello');

    // you can even chain expectations
    expect($rule)
        ->toPassWith('ANOTHER')
        ->toPassWith('TEST');
});

In a real-world test, you might want to add more cases to test this particular rule, but I hope this example makes it clear that toPassWith makes testing invokable rules very easy.

I particularly like that our test is just plain English using this syntax.

 expect($rule)->toPassWith('HELLO');

Cool, right?

If you want to use this expectation in your tests, you could opt to use our new spatie/pest-expectations package, which contains a couple of handy, opinionated custom expectations.