Tutorial: simplificando los listeners de Doctrine con `#[AsDoctrineListener]` en Symfony 6.4+

15 de octubre de 2025, 16:01:03 Diario Tecnología

En el vertiginoso mundo del desarrollo web, la eficiencia y la legibilidad del código son pilares fundamentales para mantener proyectos escalables y fáciles de mantener. Symfony, como uno de los frameworks PHP más robustos y adoptados, no cesa en su empeño por evolucionar, ofreciendo herramientas que optimizan la experiencia del desarrollador y promueven las mejores prácticas. Con las recientes versiones 6.4 y la flamante 7.0, hemos sido testigos de mejoras significativas, muchas de ellas potenciadas por las capacidades de los atributos introducidos en PHP 8. Uno de estos avances, que personalmente considero un cambio muy positivo en la forma de gestionar la interacción con la capa de persistencia, es el atributo #[AsDoctrineListener].

¿Alguna vez te has encontrado con la necesidad de ejecutar lógica específica antes o después de que una entidad sea persistida, actualizada o eliminada en la base de datos? Probablemente sí. Los listeners de Doctrine son la herramienta por excelencia para estas situaciones, pero su configuración tradicional a menudo implicaba una danza entre la definición de servicios y el etiquetado de los mismos en archivos YAML o XML. Con la llegada de #[AsDoctrineListener], este proceso se simplifica drásticamente, permitiendo una configuración declarativa y mucho más cercana al código del propio listener. Este enfoque no solo reduce la verbosidad, sino que también mejora la cohesión y la detectabilidad de los listeners. En este tutorial detallado, exploraremos a fondo este atributo, comprenderemos su utilidad y te guiaré paso a paso para implementarlo en tus proyectos Symfony, ofreciéndote código funcional y ejemplos prácticos que te permitirán dominar esta poderosa característica.

La evolución de los eventos y listeners en Symfony y Doctrine

black and red 3 round pendant

Antes de sumergirnos en la implementación de #[AsDoctrineListener], es crucial entender el contexto y la necesidad que este atributo viene a resolver. Tanto Symfony como Doctrine utilizan un patrón de diseño basado en eventos, lo que permite desacoplar componentes y añadir funcionalidad extra sin modificar el código original. Cuando hablamos de Doctrine, estos eventos son especialmente útiles para reaccionar a cambios en el estado de las entidades. Imagina escenarios como registrar la última vez que una entidad fue modificada, enviar notificaciones tras la creación de un nuevo usuario, o incluso aplicar validaciones complejas antes de guardar datos en la base de datos.

El paradigma tradicional: service tags

Históricamente, la forma de registrar un listener de Doctrine en Symfony pasaba por dos pasos principales: primero, definir tu clase listener como un servicio en el contenedor de servicios de Symfony; segundo, "etiquetar" ese servicio con una etiqueta específica (doctrine.event_listener o doctrine.event_subscriber) y, dentro de esa etiqueta, especificar los eventos a los que debía responder y, opcionalmente, la conexión o el gestor de entidades. Este método, aunque funcional y potente, presentaba ciertas desventajas.

Por ejemplo, si tenías muchos listeners, tus archivos de configuración (services.yaml) podían volverse bastante extensos y difíciles de leer. La lógica de configuración del listener estaba separada de su implementación, lo que obligaba al desarrollador a saltar entre archivos para comprender completamente cómo funcionaba un listener. Para dar un ejemplo, una configuración típica se vería así:

# config/services.yaml
services:
    App\EventListener\UserActivityListener:
        tags:
            - { name: doctrine.event_listener, event: prePersist, connection: default }
            - { name: doctrine.event_listener, event: preUpdate, connection: default }

Este enfoque funciona, pero puede ser un poco engorroso. Cada vez que querías cambiar un evento o añadir uno nuevo, debías editar este archivo de configuración. Esto, a medida que los proyectos crecen, puede generar fricción y errores difíciles de depurar, especialmente en equipos grandes.

La llegada de los atributos en PHP 8 y Symfony

Con PHP 8, llegó una característica muy esperada: los atributos. Estos permiten añadir metadatos a clases, métodos, propiedades y funciones de una manera declarativa, directamente en el código donde se definen. Symfony no tardó en adoptar esta característica para simplificar y modernizar la configuración de muchos de sus componentes, y Doctrine no fue una excepción. Los atributos proporcionan una forma más intuitiva y cercana al código para configurar servicios y sus comportamientos, moviendo la configuración desde archivos externos hacia el propio código del componente, lo que mejora la legibilidad y el mantenimiento. Creo firmemente que esta es la dirección correcta para muchos aspectos de la configuración, ya que agrupa la lógica de implementación con su configuración asociada.

Un buen punto de partida para entender más sobre los atributos en Symfony es su documentación oficial sobre atributos, que detalla cómo el framework los aprovecha para optimizar el desarrollo. Esta modernización no solo facilita la vida del desarrollador sino que también alinea a Symfony con las tendencias actuales en otros lenguajes y frameworks.

Desentrañando `#[AsDoctrineListener]`: un enfoque más elegante

El atributo #[AsDoctrineListener] fue introducido en Symfony 6.4 (y es completamente compatible con Symfony 7.0) para ofrecer una alternativa moderna y más limpia a la configuración tradicional de los listeners de Doctrine. Su propósito es permitirte registrar un servicio como un listener de Doctrine de manera declarativa, directamente en la definición de la clase del listener, eliminando la necesidad de las etiquetas en services.yaml.

Requisitos y preparación del entorno

Para seguir este tutorial, necesitarás un proyecto Symfony 6.4 o superior (idealmente Symfony 7.0 para estar a la última). Asegúrate de tener instalado Doctrine ORM y sus paquetes relacionados. Si estás empezando desde cero, puedes crear un nuevo proyecto Symfony:

composer create-project symfony/skeleton my_project_name
cd my_project_name
composer require webapp
composer require doctrine/orm symfony/maker-bundle --dev
php bin/console doctrine:database:create

Y para este ejemplo, también necesitaremos una entidad básica. Crearemos una entidad Product:

php bin/console make:entity Product

Añádele algunas propiedades, como name (string), price (float) y updatedAt (datetime_immutable, nullable por defecto para que podamos gestionarlo con el listener). Luego, genera la migración y aplícala:

php bin/console make:migration
php bin/console doctrine:migrations:migrate

El problema a resolver: una auditoría de entidades

Para demostrar la utilidad de #[AsDoctrineListener], resolveremos un problema común: queremos auditar cuándo una entidad fue modificada por última vez. Específicamente, actualizaremos automáticamente la propiedad updatedAt de nuestra entidad Product cada vez que se persista o actualice. Este es un caso de uso clásico para los eventos prePersist y preUpdate de Doctrine. Es una tarea rutinaria que, sin un enfoque adecuado, puede llevar a duplicidad de código o a que los desarrolladores olviden llamar a un método específico en cada punto de guardado. Los listeners son perfectos para centralizar esta lógica.

Implementación paso a paso con `#[AsDoctrineListener]`

Ahora que tenemos nuestro entorno preparado y un problema claro, vamos a ver cómo implementar nuestro listener utilizando el nuevo atributo.

Paso 1: creación del listener

Primero, crearemos la clase de nuestro listener. Puedes usar el comando make:subscriber o make:listener, pero en este caso, lo haremos manualmente para entender mejor la estructura. Crearemos un archivo ProductUpdatedAtListener.php dentro de src/EventListener/.

// src/EventListener/ProductUpdatedAtListener.php

namespace App\EventListener;

use App\Entity\Product;
use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener;
use Doctrine\ORM\Event\LifecycleEventArgs;
use Doctrine\ORM\Events; // Importante: para los nombres de los eventos

#[AsDoctrineListener(event: Events::prePersist)]
#[AsDoctrineListener(event: Events::preUpdate)]
class ProductUpdatedAtListener
{
    public function prePersist(LifecycleEventArgs $args): void
    {
        $entity = $args->getObject();

        // Solo actuamos si la entidad es de tipo Product
        if (!$entity instanceof Product) {
            return;
        }

        // Establecer la fecha de creación (si aún no está, para asegurar)
        // Aunque prePersist es más para esto, aquí actualizamos `updatedAt` también
        $entity->setUpdatedAt(new \DateTimeImmutable());
    }

    public function preUpdate(LifecycleEventArgs $args): void
    {
        $entity = $args->getObject();

        // Solo actuamos si la entidad es de tipo Product
        if (!$entity instanceof Product) {
            return;
        }

        // Establecer la fecha de actualización
        $entity->setUpdatedAt(new \DateTimeImmutable());

        // Doctrine necesita saber que la entidad ha sido modificada para persistir los cambios
        // en preUpdate, si el campo no se detecta automáticamente por un setter
        $em = $args->getObjectManager();
        $uow = $em->getUnitOfWork();
        $meta = $em->getClassMetadata(get_class($entity));
        $uow->recomputeSingleEntityChangeSet($meta, $entity);
    }
}

Aquí, hemos definido una clase simple con dos métodos, prePersist y preUpdate, que se encargarán de actualizar la propiedad updatedAt de nuestra entidad Product. La línea crucial es $uow->recomputeSingleEntityChangeSet($meta, $entity); en preUpdate, la cual es necesaria para que Doctrine reconozca el cambio en la entidad si se ha modificado una propiedad después de que Doctrine ya haya calculado su "cambio" inicial (lo que sucede justo antes de llamar a preUpdate). Sin esa línea, tu cambio en updatedAt podría no persistirse.

Paso 2: registro del listener con el atributo

¡Y aquí viene la magia! En lugar de ir a services.yaml, simplemente añadimos el atributo #[AsDoctrineListener] directamente sobre la clase de nuestro listener. Observa las dos líneas justo antes de la definición de la clase:

use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener;
use Doctrine\ORM\Events; // Importante: para los nombres de los eventos

#[AsDoctrineListener(event: Events::prePersist)]
#[AsDoctrineListener(event: Events::preUpdate)]
class ProductUpdatedAtListener
{
// ... métodos del listener ...
}

Con estas dos líneas, hemos registrado nuestra clase ProductUpdatedAtListener para escuchar los eventos prePersist y preUpdate de Doctrine. El event: parámetro es donde especificas a qué evento de Doctrine debe responder este listener. Los nombres de los eventos (como prePersist, preUpdate, postPersist, etc.) se encuentran convenientemente definidos como constantes en la clase Doctrine\ORM\Events. Puedes pasar múltiples atributos #[AsDoctrineListener] si tu listener necesita responder a varios eventos, como es nuestro caso.

Este es el punto central del tutorial. La limpieza y la inmediatez de la configuración son, en mi opinión, una mejora sustancial. Ya no hay necesidad de buscar en un archivo de configuración separado para entender qué eventos escucha un listener; todo está agrupado lógicamente.

Paso 3: configuración adicional (opcional pero útil)

El atributo #[AsDoctrineListener] ofrece más opciones además del evento. Puedes especificar:

  • connection: Para limitar el listener a una conexión de base de datos específica (útil en entornos multiconexión).
  • entityManager: Para limitar el listener a un gestor de entidades específico (si tienes varios).
  • priority: Para definir la prioridad de ejecución del listener si hay varios escuchando el mismo evento. Por defecto es 0.

Por ejemplo, si tuvieras una conexión llamada audit_db y quisieras que tu listener solo funcionara allí:

#[AsDoctrineListener(event: Events::prePersist, connection: 'audit_db', priority: 10)]

En nuestro caso, con la configuración por defecto y una sola conexión, no es necesario especificar estos parámetros, pero es bueno saber que existen para situaciones más complejas.

Paso 4: probando nuestro listener

Para verificar que nuestro listener funciona correctamente, podemos crear un controlador simple o usar la consola para interactuar con la entidad Product.

Creemos un controlador de prueba:

php bin/console make:controller ProductTestController

Modifica el archivo src/Controller/ProductTestController.php:

// src/Controller/ProductTestController.php

namespace App\Controller;


use App\Entity\Product;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;


class ProductTestController extends AbstractController
{
#[Route('/product/test', name: 'app_product_test')]
public function test(EntityManagerInterface $entityManager): Response
{
// Crear un nuevo producto
$product = new Product();
$product->setName('Test Product');
$product->setPrice(19.99);


    $entityManager->persist($product);
    $entityManager->flush(); // prePersist debería ejecutarse aquí

    $this->addFlash('success', sprintf('Producto creado: %s (ID: %d, UpdatedAt: %s)', $product->getName(), $product->getId(), $product->getUpdatedAt()->format('Y-m-d H:i:s')));

    // Modificar el producto
    $product->setName('Updated Test Product');
    $product->setPrice(29.99);
    $entityManager->flush(); // preUpdate debería ejecutarse aquí

    $this->addFlash('success', sprintf('Producto actualizado: %s (ID: %d, UpdatedAt: %s)', $product->getName(), $product->getId(), $product->getUpdatedAt()->format('Y-m-d H:i:s')));

    return $this->render('product_test/index.html.twig', [
        'product' => $product,
    ]);
}



}

Y la vista templates/product_test/index.html.twig (muy básica para el ejemplo):

<!DOCTYPE html>
<html>
<head>
    <title>Prueba de Producto</title>
</head>
<body>
    <h1>Resultado de la prueba de Producto</h1>

&lt;p&gt;Nombre: {{ product.name }}&lt;/p&gt;
&lt;p&gt;Precio: {{ product.price }}&lt;/p&gt;
&lt;p&gt;Actualizado en: {{ product.updatedAt|date('Y-m-d H:i:s') }}&lt;/p&gt;

&lt;div&gt;
    {% for message in app.flashes('success') %}
        &lt;div style="background-color: #d4edda; color: #155724; border: 1px solid #c3e6cb; padding: 10px; margin-bottom: 10px;"&gt;
            {{ message }}
        &lt;/div&gt;
    {% endfor %}
&lt;/div&gt;



</body>
</html>

Ahora, inicia tu servidor web de Symfony:

symfony serve

Y visita http://127.0.0.1:8000/product/test en tu navegador. Deberías ver cómo el campo updatedAt se establece automáticamente tanto al crear como al actualizar el producto, mostrando la fecha y hora actual. Esto confirma que tus listeners están funcionando perfectamente gracias al atributo #[AsDoctrineListener].

Si quieres profundizar en los eventos de Doctrine, la documentación de eventos de Doctrine ORM es un recurso invaluable. También, te recomiendo explorar la documentación de Symfony sobre listeners y subscribers de Doctrine para ver otras formas de trabajar con ellos.

Beneficios y consideraciones

El uso de #[AsDoctrineListener] no es solo una cuestión de preferencia estética; trae consigo ventajas tangibles para el desarrollo y mantenimiento de aplicaciones Symfony.

Ventajas de este enfoque

  • Claridad y Cohesión: La configuración del listener está directamente junto a su implementación. Esto mejora drásticamentela legibilidad del código. Un desarrollador nuevo en el proyecto puede entender instantáneamente qué eventos escucha un listener con solo mirar la clase.
  • Menos Archivos de Configuración: Reduce la cantidad de código y configuración en services.yaml o XML, simplificando la estructura del proyecto y minimizando la probabilidad de errores de configuración. Personalmente, valoro mucho tener menos ruido en los archivos de configuración.
  • Mayor Detectabilidad: Con IDEs modernos (como PhpStorm), es fácil navegar a la definición del atributo y ver qué otras clases lo utilizan, lo que facilita el descubrimiento de listeners existentes.
  • Mantenimiento Simplificado: Al mover la configuración del listener más cerca de su lógica, las actualizaciones y modificaciones se vuelven más directas y menos propensas a errores. Si un listener se elimina, su configuración se va con él.
  • Adopción de Estándares Modernos: Alinea el desarrollo con las capacidades más recientes de PHP 8 y las tendencias de diseño de frameworks modernos, lo que es siempre una buena señal de un proyecto bien mantenido.

Posibles limitaciones y cuándo no usarlo

Aunque #[AsDoctrineListener] es una herramienta fantástica, como cualquier otra, tiene sus matices. No siempre es la solución perfecta para todos los escenarios:

  • Compatibilidad de Versiones: Lógicamente, este atributo requiere PHP 8+ y Symfony 6.4+ (o 7.0). Si trabajas con versiones anteriores, deberás seguir usando el método tradicional de service tags.
  • Configuración Dinámica Compleja: Para escenarios donde la config