Vai al contenuto

Eventi vs messaggi in Symfony: cosa li distingue e perché conta

In molti progetti Symfony la parola “evento” viene usata per indicare cose molto diverse: un oggetto passato all’EventDispatcher, un messaggio messo in coda su RabbitMQ, un webhook inviato a un altro servizio. Finché l’applicazione è piccola la confusione non fa danni. Quando i servizi diventano tanti, invece, mescolare questi concetti produce codice difficile da seguire, contratti fragili tra sistemi e, nei casi peggiori, notifiche per operazioni che non sono mai andate a buon fine.

In questo articolo separiamo i tre concetti (evento, messaggio e trasporto) e li mettiamo al lavoro su un esempio concreto: un e-commerce che registra un ordine e deve avvisare magazzino, fatturazione e spedizioni. Useremo PHP 8.2+ e i componenti EventDispatcher e Messenger di Symfony.

Tre domande diverse

Quando un sistema deve “reagire a qualcosa”, in realtà sta rispondendo a tre domande distinte, che conviene affrontare nell’ordine giusto:

  • Cosa è successo? È l’evento: un fatto del dominio, già avvenuto e non più modificabile. “L’ordine è stato effettuato.”
  • A chi va comunicato, e in che modo? È il messaggio: la forma in cui l’informazione viaggia verso qualcun altro. Può essere sincrono o asincrono, rivolto a un solo destinatario o a molti.
  • Con quale mezzo viene consegnato? È il trasporto: RabbitMQ, Kafka, una chiamata HTTP, una tabella usata come coda.

Schema in tre colonne: evento (cosa è successo), messaggio (a chi e come comunicarlo), trasporto (con cosa consegnarlo)

L’errore più comune è partire dalla fine: “usiamo RabbitMQ”, e solo dopo chiedersi cosa inviare e a chi. Il trasporto è un dettaglio infrastrutturale: deve poter cambiare senza toccare il dominio, e lo si sceglie solo dopo aver risposto alle prime due domande.

L’evento di dominio

Un evento di dominio descrive un fatto rilevante per il business. Alcune regole pratiche:

  • il nome è al passato e usa il linguaggio del dominio: OrdineEffettuato, PagamentoConfermato, non OrdineSalvato o InsertOrdine;
  • è immutabile: un fatto accaduto non si modifica;
  • contiene i dati essenziali per capire cosa è successo, senza trascinarsi dietro l’intera entità;
  • non sa nulla di code, JSON o HTTP.
namespace App\Vendite\Dominio\Evento;

interface EventoDiDominio
{
    public function avvenutoIl(): \DateTimeImmutable;
}
namespace App\Vendite\Dominio\Evento;

final readonly class OrdineEffettuato implements EventoDiDominio
{
    public function __construct(
        public string $ordineId,
        public string $clienteId,
        public int $totaleCentesimi,
        public string $valuta,
        private \DateTimeImmutable $avvenutoIl = new \DateTimeImmutable(),
    ) {
    }

    public function avvenutoIl(): \DateTimeImmutable
    {
        return $this->avvenutoIl;
    }
}

Le classi readonly (PHP 8.2) garantiscono l’immutabilità senza scrivere getter. L’importo è in centesimi, come intero: un evento che circola tra componenti non dovrebbe mai portare con sé gli arrotondamenti dei float.

Dove nasce un evento: dentro l’aggregato

Un evento di dominio dovrebbe nascere nel punto in cui il fatto accade, cioè nel metodo dell’entità (l’aggregato, nel lessico DDD) che applica la regola di business. Se lo creassimo nel controller, chiunque modifichi l’ordine da un altro punto (un comando da console, un import, un’API) potrebbe dimenticarsi di emetterlo.

L’aggregato però non deve diffondere l’evento: si limita a registrarlo. Diffonderlo nel costruttore o nel metodo di dominio significherebbe avvisare il mondo di un ordine che magari non verrà mai salvato, perché la validazione successiva fallisce o il database rifiuta la scrittura. Un piccolo trait gestisce la registrazione:

namespace App\Condiviso\Dominio;

use App\Vendite\Dominio\Evento\EventoDiDominio;

interface AggregatoConEventi
{
    /** @return list<EventoDiDominio> */
    public function rilasciaEventi(): array;
}

trait RegistraEventi
{
    /** @var list<EventoDiDominio> */
    private array $eventiRegistrati = [];

    protected function registra(EventoDiDominio $evento): void
    {
        $this->eventiRegistrati[] = $evento;
    }

    public function rilasciaEventi(): array
    {
        $eventi = $this->eventiRegistrati;
        $this->eventiRegistrati = [];

        return $eventi;
    }
}

L’entità usa il trait e registra gli eventi nei suoi metodi di business. La proprietà $eventiRegistrati non è mappata da Doctrine, quindi non finisce nel database:

namespace App\Vendite\Dominio;

use App\Condiviso\Dominio\AggregatoConEventi;
use App\Condiviso\Dominio\RegistraEventi;
use App\Vendite\Dominio\Evento\OrdineEffettuato;
use App\Vendite\Dominio\Evento\PagamentoConfermato;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Ordine implements AggregatoConEventi
{
    use RegistraEventi;

    #[ORM\Id]
    #[ORM\Column(length: 36)]
    private string $id;

    #[ORM\Column(length: 36)]
    private string $clienteId;

    #[ORM\Column]
    private int $totaleCentesimi;

    #[ORM\Column(length: 3)]
    private string $valuta;

    #[ORM\Column(enumType: StatoOrdine::class)]
    private StatoOrdine $stato;

    private function __construct()
    {
    }

    public static function effettua(string $id, string $clienteId, int $totaleCentesimi, string $valuta): self
    {
        if ($totaleCentesimi <= 0) {
            throw new \DomainException('Il totale di un ordine deve essere positivo.');
        }

        $ordine = new self();
        $ordine->id = $id;
        $ordine->clienteId = $clienteId;
        $ordine->totaleCentesimi = $totaleCentesimi;
        $ordine->valuta = $valuta;
        $ordine->stato = StatoOrdine::InAttesaDiPagamento;

        $ordine->registra(new OrdineEffettuato($id, $clienteId, $totaleCentesimi, $valuta));

        return $ordine;
    }

    public function getId(): string
    {
        return $this->id;
    }

    public function confermaPagamento(): void
    {
        if (StatoOrdine::InAttesaDiPagamento !== $this->stato) {
            throw new \DomainException('Solo un ordine in attesa di pagamento può essere pagato.');
        }

        $this->stato = StatoOrdine::Pagato;
        $this->registra(new PagamentoConfermato($this->id));
    }
}

Lo stato è un semplice enum di PHP 8.1, che Doctrine mappa con l’opzione enumType:

namespace App\Vendite\Dominio;

enum StatoOrdine: string
{
    case InAttesaDiPagamento = 'in_attesa_pagamento';
    case Pagato = 'pagato';
    case Annullato = 'annullato';
}

Quando si diffonde: dopo il commit

Gli eventi registrati vanno diffusi solo quando il dato è stato effettivamente salvato. Il punto naturale è il servizio applicativo (o il command handler) che orchestra l’operazione:

Sequenza in cinque passi: comando, registrazione nell’aggregato, flush e commit di Doctrine dentro la transazione; rilascio e dispatch degli eventi dopo il commit

namespace App\Vendite\Applicazione;

use App\Vendite\Dominio\Ordine;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\Uid\Uuid;
use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;

final readonly class ServizioOrdini
{
    public function __construct(
        private EntityManagerInterface $em,
        private EventDispatcherInterface $dispatcher,
    ) {
    }

    public function effettua(string $clienteId, int $totaleCentesimi, string $valuta): string
    {
        $ordine = Ordine::effettua(Uuid::v7()->toRfc4122(), $clienteId, $totaleCentesimi, $valuta);

        $this->em->persist($ordine);
        $this->em->flush(); // se fallisce, nessun evento viene diffuso

        foreach ($ordine->rilasciaEventi() as $evento) {
            $this->dispatcher->dispatch($evento);
        }

        return $ordine->getId();
    }
}

dispatch() usa come nome dell’evento il nome completo della classe, quindi non servono costanti con stringhe magiche. Quando le operazioni diventano tante, il ciclo di rilascio si può spostare in un unico punto, ad esempio un middleware del command bus o un listener Doctrine, invece di ripeterlo in ogni servizio.

Reagire dentro l’applicazione: il listener

Le reazioni che restano dentro lo stesso contesto (inviare l’email di conferma, aggiornare una statistica, invalidare una cache) sono semplici listener. Con l’attributo #[AsEventListener] l’evento a cui reagire viene dedotto dal tipo del parametro:

namespace App\Vendite\Applicazione\Listener;

use App\Vendite\Dominio\Evento\OrdineEffettuato;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener]
final readonly class InviaConfermaOrdine
{
    public function __construct(private NotificatoreClienti $notificatore)
    {
    }

    public function __invoke(OrdineEffettuato $evento): void
    {
        $this->notificatore->confermaOrdine($evento->clienteId, $evento->ordineId);
    }
}

Il dispatcher di Symfony è sincrono: i listener vengono eseguiti uno dopo l’altro, nella stessa richiesta. È semplice e prevedibile, ma un listener lento (l’invio di un’email tramite un servizio esterno) rallenta la risposta, e un’eccezione in un listener interrompe tutti quelli successivi. Per queste reazioni conviene trasformare il listener in un messaggio asincrono gestito da Messenger, come vedremo tra poco.

C’è poi un costo meno visibile: la “magia”. Leggendo ServizioOrdini non si vede chi reagisce all’ordine. Per non perdere il controllo:

  • i listener devono contenere reazioni, non regole di business. Se la validità di un ordine dipende da un listener, quella regola è nel posto sbagliato;
  • ogni listener deve essere indipendente dagli altri e non deve contare sull’ordine di esecuzione;
  • il comando php bin/console debug:event-dispatcher elenca i listener registrati per un evento: è il primo strumento da usare quando “succede qualcosa” e non si capisce perché.

Uscire dal contesto: il messaggio di integrazione

Il magazzino, la fatturazione e le spedizioni sono altri sistemi, magari scritti in altri linguaggi e mantenuti da altri team. A loro non va inviato l’oggetto OrdineEffettuato: è un dettaglio interno, che deve restare libero di cambiare con il dominio. A loro va un messaggio di integrazione, cioè un contratto pubblico con caratteristiche diverse:

Aspetto Evento di dominio Messaggio di integrazione
Pubblico Il codice dello stesso contesto Altri servizi e altri team
Forma Oggetto PHP in memoria Dati serializzati (di solito JSON)
Stabilità Cambia insieme al dominio Contratto versionato, cambia con cautela
Nome OrdineEffettuato shop.ordine.effettuato.v1
Contenuto Tipi del dominio (enum, value object) Solo tipi primitivi e formati standard
Consegna Dispatcher in memoria Un trasporto: coda, broker, HTTP

Nel contesto Vendite l’evento OrdineEffettuato attiva listener interni e un traduttore che produce il messaggio shop.ordine.effettuato.v1, inviato via RabbitMQ a Magazzino, Fatturazione e Spedizioni

Il passaggio dall’uno all’altro è un compito esplicito: un traduttore che ascolta l’evento interno e produce il messaggio esterno. Il messaggio è una classe a sé, con un nome versionato e solo dati primitivi:

namespace App\Vendite\Integrazione\Messaggio;

use Symfony\Component\Messenger\Attribute\AsMessage;

#[AsMessage('ordini_out')]
final readonly class OrdineEffettuatoV1
{
    public const TIPO = 'shop.ordine.effettuato.v1';

    public function __construct(
        public string $idMessaggio,
        public string $ordineId,
        public string $clienteId,
        public string $totale,     // decimale come stringa: "49.90"
        public string $valuta,     // ISO 4217: "EUR"
        public string $avvenutoIl, // ISO 8601
    ) {
    }
}

L’attributo #[AsMessage], disponibile da Symfony 7.2, indica a Messenger su quale trasporto instradare il messaggio. È un’alternativa alla sezione routing di messenger.yaml, che se presente ha la precedenza. Il traduttore:

namespace App\Vendite\Integrazione;

use App\Vendite\Dominio\Evento\OrdineEffettuato;
use App\Vendite\Integrazione\Messaggio\OrdineEffettuatoV1;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\Messenger\Bridge\Amqp\Transport\AmqpStamp;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Uid\Uuid;

#[AsEventListener]
final readonly class PubblicaOrdineEffettuato
{
    public function __construct(private MessageBusInterface $bus)
    {
    }

    public function __invoke(OrdineEffettuato $evento): void
    {
        $messaggio = new OrdineEffettuatoV1(
            idMessaggio: Uuid::v7()->toRfc4122(),
            ordineId: $evento->ordineId,
            clienteId: $evento->clienteId,
            totale: number_format($evento->totaleCentesimi / 100, 2, '.', ''),
            valuta: $evento->valuta,
            avvenutoIl: $evento->avvenutoIl()->format(\DATE_ATOM),
        );

        $this->bus->dispatch($messaggio, [new AmqpStamp(OrdineEffettuatoV1::TIPO)]);
    }
}

Alcuni dettagli contano più di quanto sembri:

  • idMessaggio permette ai consumatori di riconoscere i duplicati. Con i broker la consegna è quasi sempre at-least-once: lo stesso messaggio può arrivare più volte, e chi lo riceve deve essere idempotente;
  • la versione nel nome (v1) permette di introdurre una v2 incompatibile pubblicandole entrambe per un periodo di transizione, senza rompere chi non ha ancora aggiornato;
  • niente oggetti PHP: importi come stringhe decimali e date in ISO 8601 sono leggibili da qualsiasi linguaggio.

Il trasporto, per ultimo

Solo a questo punto scegliamo come consegnare il messaggio. Con un exchange RabbitMQ di tipo topic, ogni sistema interessato crea la propria coda e si iscrive alle chiavi che gli interessano (ad esempio shop.ordine.*). Il venditore non deve sapere chi ascolta:

# config/packages/messenger.yaml
framework:
    messenger:
        failure_transport: falliti

        transports:
            ordini_out:
                dsn: '%env(MESSENGER_AMQP_DSN)%'
                serializer: messenger.transport.symfony_serializer
                options:
                    exchange:
                        name: shop.eventi
                        type: topic
                retry_strategy:
                    max_retries: 3
                    multiplier: 2

            falliti: 'doctrine://default?queue_name=falliti'

Il serializer di default di Messenger usa la serializzazione nativa di PHP, comoda tra applicazioni Symfony ma illeggibile per un consumatore scritto in Go o in Node.js. Per questo, verso l’esterno conviene il serializer basato sul componente Serializer, che produce JSON. Il corpo del messaggio pubblicato sarà simile a questo:

{
    "idMessaggio": "0193a1c2-7d4e-7f10-9c3b-2b6f8e1d4a55",
    "ordineId": "0193a1c2-7d4a-7a21-8e0f-5c9d3b7a1e42",
    "clienteId": "c-10482",
    "totale": "49.90",
    "valuta": "EUR",
    "avvenutoIl": "2026-11-18T10:15:00+01:00"
}

Verifica sempre il formato effettivo, header compresi, con un consumatore di prova prima di pubblicarlo come contratto: dipende dalla configurazione del serializer.

Se un giorno RabbitMQ venisse sostituito da Kafka, o se un partner potesse ricevere solo webhook HTTP, cambierebbero la configurazione del trasporto e al più il traduttore. Ordine, OrdineEffettuato e i listener interni resterebbero identici. È esattamente il vantaggio di aver deciso il trasporto per ultimo.

Il problema della doppia scrittura

Diffondere gli eventi dopo il flush() evita di annunciare ordini mai salvati, ma lascia aperto il caso opposto. Il commit va a buon fine e subito dopo il broker è irraggiungibile, oppure il processo si interrompe: l’ordine esiste, il messaggio no. È il classico problema della doppia scrittura (database più broker), che non si risolve con un try/catch.

La soluzione più diffusa è il pattern outbox: il messaggio da pubblicare viene salvato nello stesso database e nella stessa transazione dei dati di business, e un processo separato lo inoltra al broker. Con Messenger si può ottenere in modo semplice: si instrada il messaggio di integrazione verso un trasporto doctrine:// che usa la stessa connessione, si racchiudono il salvataggio dell’ordine e il dispatch in un’unica transazione, e un worker (messenger:consume) lo consegna poi a RabbitMQ. Se la transazione fallisce non resta nulla; se va a buon fine, il messaggio prima o poi partirà.

Quando invece l’operazione è già gestita da un command handler di Messenger, il middleware doctrine_transaction insieme allo stamp DispatchAfterCurrentBusStamp permette di trattenere i messaggi finché la gestione del comando non è terminata.

Errori da evitare

  • Pubblicare l’entità. Serializzare Ordine e mandarlo in coda espone lo schema interno e lega i consumatori a ogni modifica.
  • Eventi “CRUD”. OrdineAggiornato con tutti i campi non dice cosa è successo. IndirizzoDiSpedizioneCambiato sì.
  • Dispatch prima del salvataggio. Fa partire email e messaggi per operazioni poi annullate.
  • Logica di business nei listener. Le regole stanno nell’aggregato; i listener reagiscono.
  • Messenger al centro dell’architettura. Messenger è un ottimo strumento di trasporto e di esecuzione asincrona, ma il modello del dominio non deve dipendere da lui.
  • Consumatori non idempotenti. Prima o poi un messaggio arriverà due volte.

Conclusione

Distinguere eventi, messaggi e trasporto non è un esercizio accademico: è ciò che permette a un sistema di crescere senza che ogni modifica interna si propaghi a tutti i servizi collegati. L’evento racconta un fatto con il linguaggio del dominio e nasce nell’aggregato. Il messaggio traduce quel fatto in un contratto stabile per chi sta fuori. Il trasporto si limita a consegnarlo, e lo si sceglie per ultimo.

Per approfondire: la documentazione ufficiale di EventDispatcher e di Messenger.