Como funcionam eventos e listeners?

Question

Accepted Answer

O sistema de **eventos e listeners** do Laravel implementa o padrão observer — você **dispara um evento** quando algo notável acontece, e um ou mais **listeners** reagem a isso. Isso desacopla o código: a fonte do evento não precisa saber quem responde, permitindo uma separação clara de responsabilidades.

## Definindo um evento e um listener

```php
// the event — a simple data carrier for "something happened"
class OrderShipped {
    public function __construct(public Order $order) {}
}

// a listener — reacts to the event
class SendShipmentNotification {
    public function handle(OrderShipped $event): void {
        Mail::to($event->order->customer)->send(new ShipmentMail($event->order));
    }
}
// generate with: php artisan make:event / make:listener
```

## Disparando o evento

```php
// when the order ships, DISPATCH the event — all listeners run
OrderShipped::dispatch($order);
// or: event(new OrderShipped($order));
```

Disparar o evento ativa todos os seus listeners registrados. O código de envio de pedidos apenas anuncia o que aconteceu — não sabe (nem se importa) que emails, análises ou outras reações ocorrem.

## Múltiplos listeners para um evento (desacoplamento)

```php
// one event can have MANY listeners — each a separate concern
OrderShipped → SendShipmentNotification    // email
            → UpdateInventory               // adjust stock
            → RecordAnalytics               // log the event
// add reactions without modifying the order-shipping code
```

Este é o principal benefício: você pode adicionar novas reações (um listener) a um evento sem modificar o código que o dispara — desacoplamento limpo e extensível.

## Listeners enfileirados (assíncrono)

```php
class SendShipmentNotification implements ShouldQueue {   // run the listener in the BACKGROUND
    public function handle(OrderShipped $event): void { ... }
}
```

Implementar `ShouldQueue` faz um listener executar **de forma assíncrona** através da fila — para que reações lentas (enviar email) não atrasem a resposta.

## Por que isso importa

Eventos e listeners são um recurso útil do Laravel para **desacoplar** código — permitindo que diferentes partes de uma aplicação reajam a ocorrências sem acoplamento rígido, o que é valioso para reações transversais e para manter o código mantível.

Compreendê-los é útil tanto para usá-los quanto para reconhecê-los em bases de código: o padrão permite que você dispare um evento quando algo significativo acontece (um pedido é enviado, um usuário se registra) e tenha múltiplos listeners independentes reagindo (enviar email, atualizar inventário, registrar análises), cada um tratando uma responsabilidade separada.

O principal benefício é a **extensibilidade através do desacoplamento** — você pode adicionar novas reações registrando um listener sem modificar o código que dispara o evento, mantendo as responsabilidades separadas e o código de disparo focado.

A capacidade de fazer listeners **enfileirados** (`ShouldQueue`) para que executem de forma assíncrona também é importante, permitindo que reações lentas (emails, chamadas de API externas) aconteçam em segundo plano sem atrasar a resposta do usuário.

Saber como funcionam eventos/listeners, seu benefício de desacoplamento e listeners enfileirados para processamento assíncrono é conhecimento valioso para construir aplicações Laravel bem estruturadas e extensíveis. (Como com sinais em outros frameworks, a ressalva é que eventos criam comportamentos implícitos e de ação à distância que podem ser mais difíceis de rastrear — portanto, são melhor usados para genuíno desacoplamento transversal em vez de como padrão para toda a lógica pós-ação, onde código explícito geralmente é mais claro.)