Runnable

Run and fake focused PHP classes using Laravel's container.

Installation · Usage · Testing

Runnable gives your action and query classes a familiar way to run, with results you can easily fake in tests.

Test an order payment without contacting the payment provider:

Requirements

• PHP 8.2 or higher (PHP 8.3 or higher for Laravel 13)
• Laravel 12 or 13

Installation

The service provider is automatically registered. There is no configuration to publish.

Usage

Add the Runnable trait to a class with a public handle() method:

Running Classes

Using the trait:

Using the facade:

Using the helper:

All three run handle() synchronously and return its result. Arguments, including named arguments, are forwarded to handle(), and exceptions propagate to the caller. For the facade and helper, pass the class as the first positional argument.

The facade and helper work without the trait. You can also inject your class and call handle() directly.

Running Instances

Using the facade:

Using the helper:

Runnable executes the supplied instance unless you have registered a fake for its class. Ordinary container bindings do not replace it.

Testing

Call fake() before exercising your application code to replace a runnable's result and verify its calls:

The same fake works with all three execution styles and subsequent container resolutions, including dependency injection. Use it within Laravel application tests so the container and Mockery are reset between tests.

Fakes intercept handle(), so an inline instance's constructor still runs. Calling handle() directly on a real instance bypasses Runnable.

The returned fake supports Mockery assertions, including checking that it was never called:

You can also register a fake through the facade, including for classes without the trait:

Pass null explicitly to return null. Omitting the result uses Mockery's default for the method's return type. Supplied results must satisfy that type.

Faking Callbacks

Provide a closure when the result depends on the arguments: