IronWoods.es

Blog / Laravel / Eventos y Listeners en Laravel 11

Los eventos se usan para desacoplar lógica de los controladores o pŕacticas concretas como el uso de websockets.

Ubicar listeners y eventos

Si usamos eventos, éstos irán generalmente acompañados de listeners.

Por defecto los listeners se añadirán en "app/Listeners/" y los eventos en "app/Events/". Si creamos las clases con Artisan se situarán en esos directorios. Además, el sistema de autodescubrimiento de Laravel busca los listeners automáticamente en el directorio correspondiente, por ello, debemos indicarlo explícitamente si vamos a usar un directorio diferente.

Incluiré mi listener en "domain/Foo/Listeners/", además más adelante pretendo ubicar otros listeners siguiendo el patrón, por ejemplo, en "domain/Baz/Listeners/".

Registro el directorio para mis listeners en "bootstrap/app.php", usando un comodín para indicar el uso de diferentes nombres de directorio dentro de "domain/":

        ->withEvents(discover: [
            __DIR__ . '/../domain/*/Listeners',
        ])

Si, además, se van a mantener listeners en el directorio original, debe indicarse:

        ->withEvents(discover: [
            __DIR__ . '/../app/Listeners',
            __DIR__ . '/../domain/*/Listeners',
        ])

Ejemplo práctico

Se va a gestionar una invitación para unirse a un grupo a un usuario.

Creo un evento y un listener asociado al mismo:

Se crean una clase de evento y la clase listener correspondiente:

    <?php

    namespace App\Listeners;

    use App\Events\FooEvent;
    use Illuminate\Contracts\Queue\ShouldQueue;
    use Illuminate\Queue\InteractsWithQueue;

    class FooListener
    {
        /**
        * Create the event listener.
        */
        public function __construct()
        {
            //
        }

        /**
        * Handle the event.
        */
        public function handle(FooEvent $event): void
        {
            //
        }
    }

Donde el evento se asocia al listener mediante el método handle del listener.

El evento y el escuchador se crean en los directorios por defecto. Hay que moverlos a sus directorios de destino y ajustar los namespaces.

Siguiendo con mi ejemplo:

Comprobar que nombres de clases y sus ubicaciones sean correctas:

Invocar eventos

Usaré el evento para desacoplar una determinada lógica de la acción recibida en el controlador, es ahí donde indico cuando se invocará el evento.

Siguiendo mi ejemplo, en mi controlador tengo un método público:

    public function invite(int $userId, int $groupId): JsonResponse

Recibe los identificadores del usuario a invitar y del grupo.

Internamente, se recupera el usuario que envió la invitación, se comprueban restricciones, etc.

Para lanzar el evento que gestionará la invitación, pueden usarse *dos métodos, la forma orientada a objetos:

    GroupInvitationEvent::dispatch(@event_params)

o usando el helper event():

    event(new GroupInvitationEvent(@event_params));

Para el primero, existen alternativas "condicionales" (desde Laravel 9):

    GroupInvitationEvent::dispatchIf($condition, $event_params);

    GroupInvitationEvent::dispatchUnless($condition, $event_params);

*y también podríamos llegar a verlo como:

    // Illuminate\Support\Facades\Event;
    Event::dispatch(new GroupInvitationEvent(@event_params));

Para usar la forma orientada a objetos la clase evento debe usar el trait Illuminate\Foundation\Events\Dispatchable y el evento recibirá los parámetros en su constructor.

En mi caso, le paso a GroupInvitationEvent, el usuario de destino, el grupo y el nombre del usuario que invito a unirse al mismo:

    /**
     * Create a new event instance.
     */
    public function __construct(
        public readonly User $destinationUser,
        public readonly Group $game,
        public readonly string $invitedByName
    )
    {}

En la clase evento no voy a añadir nada más por el momento, sólo es un contenedor que recoge algunos parámetros.

Además, de lo anterior, existen métodos especiales para testear eventos o se puede demorar la ejecución del evento a que se de cierta situación, como que se confirme la transacción en la base de datos (desde Laravel 10).

Evento lanzado, ¿y ahora qué?

Hay 3 opciones: usar el evento para emitir a cliente externo (broadcasting), y/o usar un escuchador (listener) o bien un subscriptor (subscriber).

// domain/Group/Listeners/InvitationSubscriber.php
class InvitationSubscriber
{

    public function handleUserInvitation(GroupInvitationEvent $event): void
    {
        // ...
    }

    public function handleUserApply(GroupApplicationEvent $event): void
    {
        // ...
    }

    /**
     * Register the listeners for the subscriber.
     *
     * @return array
     */
    public function subscribe(Dispatcher $events): array
    {
        return [
            GroupInvitationEvent::class => 'handleUserInvitation',
            GroupApplicationEvent::class => 'handleUserApply',
        ];
    }
}

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Event::subscribe(InvitationSubscriber::class);
    }

Escuchar eventos

En el controlador se indica cuando se produce el evento y se le pasan algunos datos, ahora hay que escuchar cuando se invoca ese evento y añadir la lógica.

Para escuchar el evento, el listener usa el método handle (or __invoke):

    /**
     * Handle the event.
     */
    public function handle(GroupInvitationEvent $event): void
    {
        // logic here
    }

Al invocar el evento le pase, entre otros argumentos, el grupo. Siendo una propiedad pública del evento puede ser accedida a través del mismo.

Dentro del método handle del listener podemos, por ejemplo, hacer un debug para probar que se ejecuta:

    /**
     *Handle the event.
     */
    public function handle(GroupInvitationEvent $event): void
    {
        dump('InvitationListener@handle - Group ID: ' . $event->group->id););
    }

Hacemos la llamada al método del controlador que desencadena el evento. Si no hay errores, tampoco deberíamos ver el debug, primero deberemos cachear el nuevo evento.

Con el evento/listener cacheado ya deberíamos ver el debug al llamar al método del controlador.

Además del método handle, el constructor de la clase listener nos permite inyectar automáticamente las dependencias que se requiera, ya que los listeners son resueltos por el service container de Laravel.

Sitios consultados

• Documentacion de eventos Laravel 11
• Tutorial con Laravel y pusher (inglés)
• ¿Cómo usar websockets en Laravel?

28-06-2025

Entradas relacionadas:

• Estructura de directorios de Laravel