Creación de un Sistema de Eventos y Dispatcher Personalizado en PHP

🚀 Introducción al Patrón Observer y los Sistemas de Eventos en PHP

En el desarrollo de software moderno, mantener un código limpio, desacoplado y fácil de mantener es uno de los mayores desafíos. A medida que nuestras aplicaciones en PHP crecen, es común encontrarnos con controladores o servicios sobrecargados de lógica secundaria (como enviar correos electrónicos, registrar logs o actualizar cachés tras registrar un usuario).

Para solucionar esto, el patrón de diseño Observer y los sistemas basados en Eventos (Event Dispatcher) se convierten en nuestras mejores herramientas. Un Intermedio Arquitectura nivel de abstracción nos permite que diferentes componentes se comuniquen entre sí sin conocerse directamente.

🎯 ¿Qué es un Event Dispatcher y por qué lo necesitas?

Imagina que estás construyendo una tienda online. Cuando un usuario completa un pedido, deben ocurrir varias cosas:

1. Guardar la orden en la base de datos.
2. Enviar un correo de confirmación.
3. Notificar al sistema de inventario.
4. Registrar la métrica en Google Analytics.

Si pones todo esto dentro del mismo método del controlador, tu código se vuelve rígido y difícil de probar. Con un Dispatcher de Eventos, el controlador simplemente dice: "Oigan, el pedido ha sido creado" (lanza un evento) y se olvida de lo demás. Los "oyentes" o Listeners que estén suscritos a ese evento se encargarán del resto de las tareas de forma independiente.

🛠️ Requisitos Previos y Configuración del Proyecto

Para seguir este tutorial de manera óptima, asegúrate de cumplir con lo siguiente:

• PHP 8.1 o superior instalado en tu entorno local.
• Composer para la gestión de autoloader (PSR-4).
• Un editor de código como VS Code o PhpStorm.

Estructura de Directorios

Vamos a crear una estructura limpia para nuestra librería o componente:

mi-proyecto-eventos/
├── composer.json
├── src/
│   ├── Event.php
│   ├── EventDispatcher.php
│   ├── StoppableEventInterface.php
│   └── ListenerProviderInterface.php
├── examples/
│   └── index.php
└── tests/

Configura tu archivo composer.json para habilitar la carga automática PSR-4:

{
    "name": "tu-nombre/event-dispatcher",
    "description": "Un sistema de eventos personalizado en PHP",
    "type": "library",
    "autoload": {
        "psr-4": {
            "App\\EventDispatcher\\": "src/"
        }
    },
    "authors": [
        {
            "name": "Desarrollador PHP"
        }
    ],
    "minimum-stability": "stable"
}

Ejecuta el siguiente comando en tu terminal para generar el autoloader:

composer dump-autoload

🏗️ Construyendo los Componentes Principales

1. La Clase Base de Eventos (Event.php)

Un evento es simplemente un objeto portador de datos que viaja a través del sistema. En PHP 8+, podemos aprovechar las propiedades de solo lectura o constructores promovidos.

namespace App\EventDispatcher;

class Event
{
    protected bool $propagationStopped = false;

    public function isPropagationStopped(): bool
    {
        return $this->propagationStopped;
    }

    public function stopPropagation(): void
    {
        $this->propagationStopped = true;
    }
}

2. El Dispatcher de Eventos (EventDispatcher.php)

El Dispatcher es el corazón del sistema. Su trabajo es recibir eventos y despacharlos a los listeners correspondientes.

namespace App\EventDispatcher;

class EventDispatcher
{
    private array $listeners = [];

    public function addListener(string $eventName, callable $listener, int $priority = 0): void
    {
        $this->listeners[$eventName][$priority][] = $listener;
        
        // Ordenar por prioridad (mayor número = mayor prioridad)
        krsort($this->listeners[$eventName]);
    }

    public function dispatch(object $event): object
    {
        $eventName = get_class($event);

        if (!isset($this->listeners[$eventName])) {
            return $event;
        }

        foreach ($this->listeners[$eventName] as $priority => $listeners) {
            foreach ($listeners as $listener) {
                if ($event instanceof Event && $event->isPropagationStopped()) {
                    return $event;
                }

                call_user_func($listener, $event);
            }
        }

        return $event;
    }
}

🧪 Poniendo a Prueba el Sistema con un Ejemplo Real

Vamos a crear un ejemplo práctico donde simularemos el registro de un usuario en una plataforma.

Creando el Evento de Usuario Registrado

Crea un archivo llamado UserRegisteredEvent.php dentro de una nueva carpeta src/Events/:

namespace App\EventDispatcher\Events;

use App\EventDispatcher\Event;

class UserRegisteredEvent extends Event
{
    public function __construct(
        public readonly string $username,
        public readonly string $email
    ) {}
}

Creando los Listeners

Ahora crearemos dos listeners diferentes: uno para enviar un email de bienvenida y otro para registrar la actividad en un archivo de log.

namespace App\EventDispatcher\Listeners;

use App\EventDispatcher\Events\UserRegisteredEvent;

class SendWelcomeEmailListener
{
    public function __invoke(UserRegisteredEvent $event): void
    {
        echo "[Email Service] Enviando correo de bienvenida a {$event->email} ({$event->username})\n";
    }
}

class LogUserRegistrationListener
{
    public function __invoke(UserRegisteredEvent $event): void
    {
        echo "[Log Service] El usuario {$event->username} se ha registrado exitosamente.\n";
    }
}

Ejecutando todo en un Script de Prueba

Crea un archivo examples/index.php para probar nuestro sistema completo:

require_once __DIR__ . '/../vendor/autoload.php';

use App\EventDispatcher\EventDispatcher;
use App\EventDispatcher\Events\UserRegisteredEvent;
use App\EventDispatcher\Listeners\SendWelcomeEmailListener;
use App\EventDispatcher\Listeners\LogUserRegistrationListener;

// 1. Instanciar el dispatcher
$dispatcher = new EventDispatcher();

// 2. Registrar los listeners
$dispatcher->addListener(
    UserRegisteredEvent::class,
    new SendWelcomeEmailListener(),
    priority: 10
);

$dispatcher->addListener(
    UserRegisteredEvent::class,
    new LogUserRegistrationListener(),
    priority: 5
);

// 3. Simular la acción del usuario y despachar el evento
echo "Iniciando proceso de registro...\n";
$event = new UserRegisteredEvent('ana_dev', 'ana@example.com');
$dispatcher->dispatch($event);
echo "¡Proceso finalizado!\n";

Ejecuta el script desde tu terminal:

php examples/index.php

Deberías ver una salida en consola ordenada por las prioridades que definiste.

⚡ Buenas Prácticas y Consejos Avanzados

Para llevar tu sistema de eventos al siguiente nivel de producción, ten en cuenta las siguientes recomendaciones:

• Evita efectos secundarios ocultos: Los eventos deben ser independientes. Un listener no debe depender de que otro listener se ejecute primero, a menos que uses prioridades estrictamente controladas.
• Inyección de dependencias: Asegúrate de que tus listeners reciban sus dependencias (como servicios de correo o bases de datos) a través del constructor mediante un contenedor de dependencias (DIC).
• Manejo de excepciones: ¿Qué pasa si un listener lanza una excepción? Asegúrate de implementar bloques try-catch dentro del dispatcher si deseas que un error en un listener secundario no rompa toda la aplicación.

❓ Preguntas Frecuentes (FAQ)

🎓 Conclusión

¡Felicidades! Has construido tu propio Sistema de Eventos y Event Dispatcher en PHP puro. Has aprendido cómo funciona el patrón Observer, la gestión de prioridades y cómo desacoplar la lógica de tu aplicación para hacerla más modular, escalable y profesional.

Ahora puedes integrar este componente en tus propios mini-frameworks o proyectos personalizados para mejorar radicalmente su arquitectura.