Event System

O que é um Evento?

Um evento é um objeto que representa "algo que aconteceu" na aplicação. É um container de dados que transporta informação sobre a ocorrência. Eventos são imutáveis — apenas guardam dados, não contêm lógica.

<?php

final readonly class OrderCreated
{
    public function __construct(
        public int $orderId,
        public float $amount,
        public int $userId,
    ) {}
}

O que é um Listener?

Um listener é uma classe que "escuta" um evento específico e executa uma ação quando ele ocorre. Cada listener deve ter uma única responsabilidade.

<?php

class SendOrderConfirmationListener
{
    public function handle(OrderCreated $event): void
    {
        $this->mailer->send(
            to: $event->userId,
            subject: 'Pedido Confirmado',
            data: ['orderId' => $event->orderId]
        );
    }
}

O que é um Subscriber?

Um subscriber é uma classe que pode escutar múltiplos eventos. É ideal quando tens lógica relacionada que responde a vários eventos do mesmo domínio.

<?php

final readonly class OrderEventsSubscriber
{
    public function subscribe(Dispatcher $events): void
    {
        $events->listen(OrderCreated::class, $this->onOrderCreated(...));
        $events->listen(OrderShipped::class, $this->onOrderShipped(...));
        $events->listen(OrderCancelled::class, $this->onOrderCancelled(...));
    }
}

Estrutura Gerada

<?php

declare(strict_types=1);

namespace Og\Modules\Billing\Events;

final readonly class OrderCreated
{
    public function __construct(
        public readonly int $orderId,
        public readonly float $amount,
        public readonly int $userId,
    ) {
    }
}

Exemplo Completo

php og make:listener SendOrderConfirmation --module=Billing --event="Og\\Modules\\Billing\\Events\\OrderCreated"

<?php

declare(strict_types=1);

namespace Og\Modules\Billing\Listeners;

use Og\Modules\Billing\Events\OrderCreated;

class SendOrderConfirmationListener
{
    public function handle(OrderCreated $event): void
    {
        // Enviar email de confirmação
        $this->mailer->send(
            to: $event->userId,
            subject: 'Pedido Confirmado',
            data: ['orderId' => $event->orderId]
        );
    }
}

Comando com Múltiplos Eventos

php og make:subscriber OrderEventsSubscriber --module=Billing --events="OrderCreated,OrderShipped,OrderCancelled"

Estrutura do Subscriber

<?php

declare(strict_types=1);

namespace Og\Modules\Billing\Listeners;

use Illuminate\Events\Dispatcher;
use Og\Modules\Billing\Events\OrderCreated;
use Og\Modules\Billing\Events\OrderShipped;
use Og\Modules\Billing\Events\OrderCancelled;

final readonly class OrderEventsSubscriber
{
    public function __construct(private OrderAuditService $auditService)
    {
    }

    public function subscribe(Dispatcher $events): void
    {
        $events->listen(OrderCreated::class, $this->onOrderCreated(...));
        $events->listen(OrderShipped::class, $this->onOrderShipped(...));
        $events->listen(OrderCancelled::class, $this->onOrderCancelled(...));
    }

    public function onOrderCreated(OrderCreated $event): void
    {
        $this->auditService->log('created', $event->orderId);
    }

    public function onOrderShipped(OrderShipped $event): void
    {
        $this->auditService->log('shipped', $event->orderId);
    }

    public function onOrderCancelled(OrderCancelled $event): void
    {
        $this->auditService->log('cancelled', $event->orderId);
    }
}

Registo directo no boot() (Alternativa)

public function boot(): void
{
    $dispatcher = $this->app->make('events');
    
    $subscriber = $this->app->make(OrderEventsSubscriber::class);
    $subscriber->subscribe($dispatcher);
}

Uso Básico

use Og\Modules\Billing\Events\OrderCreated;

// Dentro de uma Action, Controller, Service...
event(new OrderCreated(
    orderId: $order->id,
    amount: $order->total,
    userId: $order->user_id,
));

Via Facade

use Og\Modules\Common\Facades\Event;

// Disparar evento
Event::dispatch(new OrderCreated($orderId, $amount, $userId));

// Escutar evento dinamicamente
Event::listen(OrderCreated::class, function ($event) {
    // Handle
});

// Verificar se há listeners
Event::hasListeners(OrderCreated::class);

Disparo Condicional

// Disparar apenas se condição for verdadeira
if ($shouldNotify) {
    event(new OrderCreated($orderId, $amount, $userId));
}

Evento de Interação

final readonly class SaftAoElectronicInvoicingRegisterInvoiceInteraction
{
    public function __construct(
        public readonly ?string $referenceId,
        public readonly ?int $userId,
        public readonly int|string $documentNumber,
        public readonly string $documentOperationType,
        public readonly string $submissionUuid,
        public readonly string $endpoint,
        public readonly string $sourceClass,
        public readonly string $status,
        public readonly string $endpointMethod,
        public readonly string $authorityCountry,
        public readonly ?array $payload,
        public readonly ?array $response,
    ) {}
}

Subscriber que Grava Histórico

final readonly class SaftAoElectronicInvoicingTaxAuthoritySubmissionSubscriber
{
    public function __construct(private TaxAuthorityDocumentSubmissionRecorder $recorder)
    {
    }

    public function subscribe(Dispatcher $events): void
    {
        $events->listen(
            SaftAoElectronicInvoicingRegisterInvoiceInteraction::class,
            $this->onInteraction(...),
        );

        $events->listen(
            SaftAoElectronicInvoicingRegisterInvoiceSucceeded::class,
            $this->onSucceeded(...),
        );
    }

    public function onInteraction($event): void
    {
        $this->recorder->recordInteraction([
            'authority_reference_id' => $event->referenceId,
            'user_id' => $event->userId,
            'document_number' => (string) $event->documentNumber,
            'status' => $event->status,
            // ...
        ], $event->payload, $event->response);
    }
}

Action que Dispara os Eventos

public function handle(string $documentType, int $documentNumber): array
{
    $response = $this->postJson($endpoint, $body);
    
    // Dispara evento de interação (sempre)
    event(new SaftAoElectronicInvoicingRegisterInvoiceInteraction(
        $requestId, Auth::id(), $documentNumber, /* ... */
    ));

    if ($wasSuccessful) {
        // Dispara evento de sucesso
        event(new SaftAoElectronicInvoicingRegisterInvoiceSucceeded(
            (string) $requestId, Auth::id(), $documentNumber, /* ... */
        ));
    }

    return $result;
}

Testar Listeners Isoladamente (Recomendado)

public function test_listener_sends_email(): void
{
    // Mocka o serviço de email
    $mailerMock = $this->createMock(Mailer::class);
    $mailerMock->expects($this->once())
        ->method('send')
        ->with($this->callback(fn($params) => $params['to'] === 42));
    
    // Cria o listener com o mock
    $listener = new SendOrderConfirmationListener($mailerMock);
    
    // Cria o evento e executa o listener directamente
    $event = new OrderCreated(orderId: 123, amount: 99.99, userId: 42);
    $listener->handle($event);
}

Checklist de Debugging

• ☐ O subscriber está registado no ServiceProvider::register()?
• ☐ O ServiceProvider está listado no Container.php?
• ☐ O método subscribe() do subscriber está correto?
• ☐ O evento está a ser criado com os dados correctos?
• ☐ Há erros no log (storage/logs/)?
• ☐ As dependências do subscriber estão bindadas?

Resumo de Comandos