Decouple your controllers from business logic using the Mediator pattern (CQRS) and PHP 8 Attributes — with zero boilerplate.
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);
}
} |
|
⚡ Zero Config
Handlers are auto-discovered via |
📢 Event Bus Publish events to multiple notification handlers, with priority control over execution order. |
|
🎮 Attribute Routing
Define routes directly on Action classes with |
🔗 Pipelines
Apply middleware-like logic (transactions, logging) globally or per-handler via |
|
🧪 Testing Fakes Assert dispatched requests without executing business logic — built-in, no setup required. |
🚀 Production Cache
Eliminate discovery overhead (~2,500x faster boot) with |
composer require ignaciocastro0713/cqbus-mediatorThe package is auto-discovered. Optionally publish the config file:
php artisan vendor:publish --tag=mediator-configThe 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 --actionGenerates 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.
| 📦 Installation | 🧠 Core Concepts | ⚡ Commands & Queries |
| 📢 Event Bus | 🎮 Routing & Actions | 🔗 Pipelines |
| 🧪 Testing | 📋 Console Commands | 🚀 Production & Performance |
- PHP 8.2+
- Laravel 11.0+
Feel free to open issues or submit pull requests on the GitHub repository.
This package is open-sourced software licensed under the MIT license.