Laravel Events

Tempo de leitura: 4 minutos

Laravel Events: O sistema de Events & Listeners do Laravel implementa o padrão de design Observer (Observador), fornecendo um mecanismo elegante e desacoplado para que diferentes partes da sua aplicação se comuniquem. Quando uma ação crucial ocorre (o Evento), o sistema dispara uma notificação, e qualquer classe interessada (o Listener) pode reagir a essa notificação sem que a classe que disparou precise saber quem a está ouvindo.

Essa abordagem melhora a modularidade, a flexibilidade e a manutenção do código.

1. 📝 Gerando Eventos e Listeners

O Artisan simplifica a criação dos componentes principais.

A. Criando o Evento

O Evento é uma classe simples que contém os dados da ação ocorrida. Ela deve ser criada para qualquer ação significativa que outras partes da aplicação possam precisar reagir.

Bash

php artisan make:event UserRegistered
# Gera App/Events/UserRegistered.php

B. Criando o Listener

O Listener é uma classe que contém o código a ser executado quando o evento correspondente é disparado.

Bash

php artisan make:listener SendWelcomeEmail
# Gera App/Listeners/SendWelcomeEmail.php

2. 📡 Definindo e Registrando

A. Definição do Evento

O Evento é um contêiner de dados. Sua classe deve receber e armazenar qualquer informação necessária para que o Listener execute sua tarefa.

PHP

// app/Events/UserRegistered.php
namespace App\Events;

use App\Models\User; 
// ... outros traits (Dispatchable, SerializesModels, etc.)

class UserRegistered
{
  public $user; // O modelo de usuário que acabou de ser criado

  public function __construct(User $user)
  {
      $this->user = $user;
  }
}

B. Registro no Service Provider

Para que o Laravel saiba qual Listener ouvir qual Evento, você precisa registrá-los no array $listen do App\Providers\EventServiceProvider.php.

PHP

// app/Providers/EventServiceProvider.php

protected $listen = [
    // Quando este evento for disparado...
    \App\Events\UserRegistered::class => [
        // ... execute esta lista de listeners.
        \App\Listeners\SendWelcomeEmail::class,
        \App\Listeners\LogUserRegistration::class,
    ],
];

C. Implementação do Listener

O método crucial em um Listener é o handle(), que recebe a instância do Evento e contém a lógica de reação.

PHP

// app/Listeners/SendWelcomeEmail.php
namespace App\Listeners;

use App\Events\UserRegistered;

class SendWelcomeEmail
{
    public function handle(UserRegistered $event) // Recebe o objeto Evento
    {
        // Acesso aos dados através da propriedade pública $user do Evento
        \Mail::to($event->user->email)->send(new WelcomeEmail($event->user));
    }
}

3. 🚀 Disparando Eventos

Para notificar o sistema que uma ação ocorreu, use o helper global event() ou a Facade Event.

PHP

use App\Events\UserRegistered;

// Disparando o evento em um Controller, Service ou Model
$user = User::create($data); 

// Todos os Listeners registrados para UserRegistered serão executados sequencialmente.
event(new UserRegistered($user));

4. 🧠 Listeners em Fila (Async)

A execução padrão dos Listeners é síncrona (bloqueia o fluxo principal). Para tarefas demoradas (como enviar e-mails), você deve colocá-los em Fila (Queue).

Para que um Listener seja executado em segundo plano, ele deve implementar a interface ShouldQueue.

PHP

// app/Listeners/SendWelcomeEmail.php
use Illuminate\Contracts\Queue\ShouldQueue; // << Interface Importante

class SendWelcomeEmail implements ShouldQueue // << Implementa a interface
{
    // ... corpo do listener ...
}
// Quando o evento for disparado, este Listener será enviado para a fila

5. 🧪 Testando Eventos

Para garantir que a comunicação desacoplada funcione, você deve testar se o Evento correto foi disparado. O Laravel fornece ferramentas de fake para isolar o disparo do Evento da execução dos Listeners.

PHP

use Illuminate\Support\Facades\Event;
use App\Events\UserRegistered;

public function testUserRegistrationFiresEvent()
{
    // 1. Finge (Fake) o sistema de eventos
    Event::fake();

    // Simula a ação que dispara o evento
    $user = $this->userService->registerUser(); 

    // 2. Afirma que o evento correto foi disparado (e os listeners NÃO foram executados)
    Event::assertDispatched(UserRegistered::class, function ($event) use ($user) {
        // Opcional: Verifica se os dados do evento estão corretos
        return $event->user->id === $user->id;
    });

    // 3. Afirma que um listener específico NÃO foi executado (se necessário)
    Event::assertNotDispatched(\App\Listeners\AnotherListener::class);
}

✅ Conclusão Laravel Events

Laravel Events: O sistema de Events & Listeners é a melhor maneira de manter sua aplicação desacoplada. Ele permite que você separe a ação (Evento) da reação (Listener), facilitando a adição de novas funcionalidades sem modificar o código existente. Lembre-se de usar ShouldQueue para Listeners demorados, garantindo que o desempenho da sua aplicação permaneça rápido.

Mas antes de dominar o Laravel, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no Laravel, você precisará dominar as seguintes tecnologias: