README

A zero-configuration Command/Query Bus for Laravel

Decouple your controllers from business logic using the Mediator pattern (CQRS) and PHP 8 Attributes — with zero boilerplate.

📖 Read the Documentation

The Problem

Controllers that mix HTTP, business logic, and side effects are hard to test and maintain.

❌ Before — everything tangled in one place	✅ After — each concern in its own place
class UserController extends Controller { public function register(Request $request) { $request->validate([ 'email' => 'required\|email', 'password' => 'required', ]); DB::beginTransaction(); try { $user = User::create($request->all()); Mail::to($user)->send(new WelcomeEmail()); Log::info("User registered"); DB::commit(); return response()->json($user, 201); } catch (\Exception $e) { DB::rollBack(); throw $e; } } }	#[Api] class RegisterUserAction { use AsAction; public function __construct( private readonly Mediator $mediator ) {} public static function route(Router $router): void { $router->post('/register'); } public function handle(RegisterUserRequest $request): JsonResponse { // Handler runs the logic $user = $this->mediator->send($request); // Notifications handle side effects $this->mediator->publish(new UserRegisteredEvent($user)); return response()->json($user, 201); } }

❌ Before — everything tangled in one place

✅ After — each concern in its own place

class UserController extends Controller
{
    public function register(Request $request)
    {
        $request->validate([
            'email' => 'required|email',
            'password' => 'required',
        ]);

        DB::beginTransaction();
        try {
            $user = User::create($request->all());
            Mail::to($user)->send(new WelcomeEmail());
            Log::info("User registered");
            DB::commit();
            return response()->json($user, 201);
        } catch (\Exception $e) {
            DB::rollBack();
            throw $e;
        }
    }
}

#[Api]
class RegisterUserAction
{
    use AsAction;

    public function __construct(
        private readonly Mediator $mediator
    ) {}

    public static function route(Router $router): void
    {
        $router->post('/register');
    }

    public function handle(RegisterUserRequest $request): JsonResponse
    {
        // Handler runs the logic
        $user = $this->mediator->send($request);

        // Notifications handle side effects
        $this->mediator->publish(new UserRegisteredEvent($user));

        return response()->json($user, 201);
    }
}

Features

⚡ Zero Config Handlers are auto-discovered via `#[RequestHandler]` and `#[Notification]` attributes. No registration needed.	📢 Event Bus Publish events to multiple notification handlers, with priority control over execution order.
🎮 Attribute Routing Define routes directly on Action classes with `#[Api]`, `#[Prefix]`, `#[Middleware]`, and more.	🔗 Pipelines Apply middleware-like logic (transactions, logging) globally or per-handler via `#[Pipeline]`.
🧪 Testing Fakes Assert dispatched requests without executing business logic — built-in, no setup required.	🚀 Production Cache Eliminate discovery overhead (~2,500x faster boot) with `php artisan mediator:cache`.

Installation

composer require ignaciocastro0713/cqbus-mediator

The package is auto-discovered. Optionally publish the config file:

php artisan vendor:publish --tag=mediator-config

Quick Start

The package supports two patterns:

Pattern	Method	Direction	Use for
Command / Query	`send()`	1-to-1	Business logic that reads or writes
Event Bus	`publish()`	1-to-N	Side effects (emails, logs, etc.)

1. Scaffold your classes

php artisan make:mediator-handler RegisterUserHandler --action

Generates RegisterUserRequest, RegisterUserHandler, and RegisterUserAction in one go.

2. Write your Handler

#[RequestHandler(RegisterUserRequest::class)]
class RegisterUserHandler
{
    public function handle(RegisterUserRequest $request): User
    {
        return User::create($request->validated());
    }
}

3. Dispatch from your Action

$user = $this->mediator->send($request);

The Mediator discovers and routes to the correct handler automatically.

Documentation

📦 Installation	🧠 Core Concepts	⚡ Commands & Queries
📢 Event Bus	🎮 Routing & Actions	🔗 Pipelines
🧪 Testing	📋 Console Commands	🚀 Production & Performance

Requirements

PHP 8.2+
Laravel 11.0+

Contributing

Feel free to open issues or submit pull requests on the GitHub repository.

License

This package is open-sourced software licensed under the MIT license.

ignaciocastro0713 / cqbus-mediator

Maintainers

Package info

Statistics

Security