Event و Listener در Laravel — decouple کردن منطق با رویدادها

Controller بعد از ثبت سفارش نباید بداند چه کسی ایمیل می‌زند، SMS می‌فرستد یا analytics را آپدیت می‌کند — فقط «سفارش ثبت شد» را اعلام کند. Event/Listener الگوی decouple رسمی Laravel است. تفاوت با Observer: Observer به lifecycle یک Model چسبیده؛ Event زبان دامنه کسب‌وکار است.

ساخت Event

php artisan make:event OrderPlaced

class OrderPlaced
{
    use Dispatchable, SerializesModels;

    public function __construct(public Order $order) {}
}

Listener

php artisan make:listener SendOrderNotification --event=OrderPlaced

class SendOrderNotification implements ShouldQueue
{
    public function handle(OrderPlaced $event): void
    {
        Mail::to($event->order->user)->send(new OrderMail($event->order));
    }
}

با ShouldQueue listener به صف می‌رود — Queue.

ثبت mapping

Laravel 11+ auto-discovery اگر نام‌گذاری convention باشد؛ یا در AppServiceProvider:

Event::listen(OrderPlaced::class, SendOrderNotification::class);

Dispatch

// در OrderService بعد از commit
OrderPlaced::dispatch($order);

// یا
event(new OrderPlaced($order));

ترجیحاً بعد از transaction commit.

چند Listener یک Event

protected $listen = [
    OrderPlaced::class => [
        SendOrderNotification::class,
        UpdateAnalytics::class,
        NotifyWarehouse::class,
    ],
];

Event vs Job مستقیم

Event وقتی چند واکنش دارید یا ممکن است listener اضافه شود. Job واحد برای یک task مشخص — Job.

Subscriber class

یک کلاس چند event را handle می‌کند — برای organize کردن listenerهای مرتبط.

تست

Event::fake();
// action
Event::assertDispatched(OrderPlaced::class, fn ($e) => $e->order->id === 1);

جزئیات در Pest.

اشتباهات

• logic سنگین در listener بدون queue
• حلقه event (listener دوباره event dispatch)
• فراموش fake در تست

جمع‌بندی

Event = زبان domain. Observer = persistence hook. Broadcast: مقاله بعد. معماری: لایه‌ای.

event-driven design