Files

Michael Schiemer e26eb2aa12 feat: CI/CD pipeline setup complete - Ansible playbooks updated, secrets configured, workflow ready

2025-10-31 01:39:24 +01:00

23 KiB

Raw Blame History

Event System

This guide covers the event-driven architecture of the framework.

Overview

The framework provides a sophisticated event system built on two core components:

EventBus: Simple, lightweight interface for basic event dispatching
EventDispatcher: Full-featured implementation with handler management, priorities, and propagation control

Key Features:

Attribute-based event handler registration via #[OnEvent]
Priority-based handler execution
Event propagation control (stop propagation)
Support for inheritance and interface-based event matching
Automatic handler discovery via framework's attribute system
Domain events for business logic decoupling
Application lifecycle events for framework integration

EventBus vs EventDispatcher

EventBus Interface

Purpose: Simple contract for event dispatching

interface EventBus
{
    public function dispatch(object $event): void;
}

When to use:

Simple event dispatching without return values
Fire-and-forget events
When you don't need handler results
Dependency injection when you want interface-based type hints

Example Usage:

final readonly class OrderService
{
    public function __construct(
        private EventBus $eventBus
    ) {}

    public function createOrder(CreateOrderCommand $command): Order
    {
        $order = Order::create($command);

        // Fire event without caring about results
        $this->eventBus->dispatch(new OrderCreatedEvent($order));

        return $order;
    }
}

EventDispatcher Implementation

Purpose: Full-featured event system with handler management and results

Key Features:

Returns array of handler results
Priority-based handler execution (highest priority first)
Stop propagation support
Manual handler registration via addHandler() or listen()
Automatic handler discovery via #[OnEvent] attribute
Inheritance and interface matching

When to use:

Need handler return values for processing
Want priority control over execution order
Need to stop event propagation conditionally
Require manual handler registration
Building complex event workflows

Example Usage:

final readonly class PaymentProcessor
{
    public function __construct(
        private EventDispatcher $dispatcher
    ) {}

    public function processPayment(Payment $payment): PaymentResult
    {
        // Dispatch and collect results from all handlers
        $results = $this->dispatcher->dispatch(
            new PaymentProcessingEvent($payment)
        );

        // Process handler results
        foreach ($results as $result) {
            if ($result instanceof PaymentValidationFailure) {
                throw new PaymentException($result->reason);
            }
        }

        return new PaymentResult($payment, $results);
    }
}

Implementation Relationship

// EventDispatcher implements EventBus interface
final class EventDispatcher implements EventBus
{
    public function dispatch(object $event): array
    {
        // Full implementation with handler management
    }
}

// In DI Container
$container->singleton(EventBus::class, EventDispatcher::class);
$container->singleton(EventDispatcher::class, EventDispatcher::class);

Recommendation: Use EventDispatcher for type hints when you need full features, use EventBus interface when you want loose coupling and don't need results.

Domain Events

What are Domain Events?

Domain Events represent significant state changes or occurrences in your business domain. They enable loose coupling between domain components.

Characteristics:

Immutable (readonly classes)
Named in past tense (OrderCreated, UserRegistered, PaymentCompleted)
Contain only relevant domain data
No business logic (pure data objects)
Include timestamp for audit trail

Creating Domain Events

namespace App\Domain\Order\Events;

use App\Domain\Order\ValueObjects\OrderId;
use App\Framework\Core\ValueObjects\Timestamp;

final readonly class OrderCreatedEvent
{
    public readonly Timestamp $occurredAt;

    public function __construct(
        public OrderId $orderId,
        public UserId $userId,
        public Money $total,
        ?Timestamp $occurredAt = null
    ) {
        $this->occurredAt = $occurredAt ?? Timestamp::now();
    }
}

Best Practices:

Use Value Objects for event properties
Include timestamp for audit trail
Keep events focused (single responsibility)
Version events for backward compatibility
Document event payload in PHPDoc

Framework Lifecycle Events

The framework provides built-in events for application lifecycle:

ApplicationBooted

Triggered: After application bootstrap completes

final readonly class ApplicationBooted
{
    public function __construct(
        public \DateTimeImmutable $bootTime,
        public string $environment,
        public Version $version,
        public \DateTimeImmutable $occurredAt = new \DateTimeImmutable()
    ) {}
}

Use Cases:

Initialize services after boot
Start background workers
Setup scheduled tasks
Warm caches

BeforeHandleRequest

Triggered: Before HTTP request processing

final readonly class BeforeHandleRequest
{
    public function __construct(
        public Request $request,
        public Timestamp $timestamp,
        public array $context = []
    ) {}
}

Use Cases:

Request logging
Performance monitoring
Security checks
Request transformation

AfterHandleRequest

Triggered: After HTTP request processing

final readonly class AfterHandleRequest
{
    public function __construct(
        public Request $request,
        public Response $response,
        public Duration $processingTime,
        public Timestamp $timestamp,
        public array $context = []
    ) {}
}

Use Cases:

Response logging
Performance metrics
Analytics collection
Cleanup operations

Example: User Registration Event

namespace App\Domain\User\Events;

final readonly class UserRegisteredEvent
{
    public readonly Timestamp $occurredAt;

    public function __construct(
        public UserId $userId,
        public Email $email,
        public UserName $userName,
        ?Timestamp $occurredAt = null
    ) {
        $this->occurredAt = $occurredAt ?? Timestamp::now();
    }
}

// Dispatching the event
final readonly class UserService
{
    public function __construct(
        private UserRepository $repository,
        private EventBus $eventBus
    ) {}

    public function register(RegisterUserCommand $command): User
    {
        $user = User::create(
            $command->email,
            $command->userName,
            $command->password
        );

        $this->repository->save($user);

        // Dispatch domain event
        $this->eventBus->dispatch(
            new UserRegisteredEvent(
                $user->id,
                $user->email,
                $user->userName
            )
        );

        return $user;
    }
}

Event Handler Registration

Attribute-Based Registration

Primary Method: Use #[OnEvent] attribute for automatic discovery

use App\Framework\Core\Events\OnEvent;

final readonly class UserEventHandlers
{
    public function __construct(
        private EmailService $emailService,
        private Logger $logger
    ) {}

    #[OnEvent(priority: 100)]
    public function sendWelcomeEmail(UserRegisteredEvent $event): void
    {
        $this->emailService->send(
            to: $event->email,
            template: 'welcome',
            data: ['userName' => $event->userName->value]
        );
    }

    #[OnEvent(priority: 50)]
    public function logUserRegistration(UserRegisteredEvent $event): void
    {
        $this->logger->info('User registered', [
            'user_id' => $event->userId->toString(),
            'email' => $event->email->value,
            'occurred_at' => $event->occurredAt->format('Y-m-d H:i:s')
        ]);
    }
}

Attribute Parameters:

priority (optional): Handler execution order (higher = earlier, default: 0)
stopPropagation (optional): Stop execution after this handler (default: false)

Priority-Based Execution

Handlers execute in priority order (highest to lowest):

#[OnEvent(priority: 200)]  // Executes first
public function criticalHandler(OrderCreatedEvent $event): void { }

#[OnEvent(priority: 100)]  // Executes second
public function highPriorityHandler(OrderCreatedEvent $event): void { }

#[OnEvent(priority: 50)]   // Executes third
public function normalHandler(OrderCreatedEvent $event): void { }

#[OnEvent]                 // Executes last (default priority: 0)
public function defaultHandler(OrderCreatedEvent $event): void { }

Use Cases for Priorities:

Critical (200+): Security checks, validation, fraud detection
High (100-199): Transaction logging, audit trail
Normal (50-99): Business logic, notifications
Low (0-49): Analytics, metrics, cleanup

Stop Propagation

Purpose: Prevent subsequent handlers from executing

#[OnEvent(priority: 100, stopPropagation: true)]
public function validatePayment(PaymentProcessingEvent $event): PaymentValidationResult
{
    $result = $this->validator->validate($event->payment);

    if (!$result->isValid()) {
        // Stop propagation - no further handlers execute
        return new PaymentValidationFailure($result->errors);
    }

    return new PaymentValidationSuccess();
}

#[OnEvent(priority: 50)]
public function processPayment(PaymentProcessingEvent $event): void
{
    // This handler only executes if validation passes
    // (previous handler didn't set stopPropagation result)
    $this->gateway->charge($event->payment);
}

Important: stopPropagation stops execution after the current handler completes.

Manual Handler Registration

Alternative: Register handlers programmatically

final readonly class EventInitializer
{
    public function __construct(
        private EventDispatcher $dispatcher
    ) {}

    #[Initializer]
    public function registerHandlers(): void
    {
        // Using listen() method
        $this->dispatcher->listen(
            OrderCreatedEvent::class,
            function (OrderCreatedEvent $event) {
                // Handle event
            },
            priority: 100
        );

        // Using addHandler() method
        $this->dispatcher->addHandler(
            eventClass: UserRegisteredEvent::class,
            handler: [$this->userService, 'onUserRegistered'],
            priority: 50
        );
    }
}

When to use manual registration:

Dynamic handler registration based on configuration
Third-party library integration
Closure-based handlers for simple cases
Runtime handler modification

Handler Discovery

The framework automatically discovers handlers marked with #[OnEvent]:

// In Application Bootstrap
final readonly class EventSystemInitializer
{
    #[Initializer]
    public function initialize(EventDispatcher $dispatcher): void
    {
        // Automatic discovery finds all #[OnEvent] methods
        $discoveredHandlers = $this->attributeScanner->findMethodsWithAttribute(
            OnEvent::class
        );

        foreach ($discoveredHandlers as $handler) {
            $dispatcher->addHandler(
                eventClass: $handler->getEventClass(),
                handler: [$handler->instance, $handler->method],
                priority: $handler->attribute->priority ?? 0
            );
        }
    }
}

No Manual Setup Required: Framework handles discovery automatically during initialization.

Event Middleware

Concept: Middleware pattern for event processing (transform, filter, log, etc.)

Custom Event Middleware

interface EventMiddleware
{
    public function process(object $event, callable $next): mixed;
}

final readonly class LoggingEventMiddleware implements EventMiddleware
{
    public function __construct(
        private Logger $logger
    ) {}

    public function process(object $event, callable $next): mixed
    {
        $eventClass = get_class($event);
        $startTime = microtime(true);

        $this->logger->debug("Event dispatched: {$eventClass}");

        try {
            $result = $next($event);

            $duration = (microtime(true) - $startTime) * 1000;
            $this->logger->debug("Event processed: {$eventClass}", [
                'duration_ms' => $duration
            ]);

            return $result;
        } catch (\Throwable $e) {
            $this->logger->error("Event failed: {$eventClass}", [
                'error' => $e->getMessage()
            ]);
            throw $e;
        }
    }
}

Middleware Pipeline

final class EventDispatcherWithMiddleware
{
    /** @var EventMiddleware[] */
    private array $middleware = [];

    public function addMiddleware(EventMiddleware $middleware): void
    {
        $this->middleware[] = $middleware;
    }

    public function dispatch(object $event): array
    {
        $pipeline = array_reduce(
            array_reverse($this->middleware),
            fn($next, $middleware) => fn($event) => $middleware->process($event, $next),
            fn($event) => $this->eventDispatcher->dispatch($event)
        );

        return $pipeline($event);
    }
}

Validation Middleware

final readonly class ValidationEventMiddleware implements EventMiddleware
{
    public function __construct(
        private ValidatorInterface $validator
    ) {}

    public function process(object $event, callable $next): mixed
    {
        // Validate event before dispatching
        $errors = $this->validator->validate($event);

        if (!empty($errors)) {
            throw new InvalidEventException(
                "Event validation failed: " . implode(', ', $errors)
            );
        }

        return $next($event);
    }
}

Async Event Processing

Queue-Based Async Handling

use App\Framework\Queue\Queue;
use App\Framework\Queue\ValueObjects\JobPayload;

final readonly class AsyncEventHandler
{
    public function __construct(
        private Queue $queue
    ) {}

    #[OnEvent(priority: 50)]
    public function processAsync(OrderCreatedEvent $event): void
    {
        // Dispatch to queue for async processing
        $job = new ProcessOrderEmailJob(
            orderId: $event->orderId,
            userEmail: $event->userEmail
        );

        $this->queue->push(
            JobPayload::immediate($job)
        );
    }
}

// Background Job
final readonly class ProcessOrderEmailJob
{
    public function __construct(
        public OrderId $orderId,
        public Email $userEmail
    ) {}

    public function handle(EmailService $emailService): void
    {
        // Process email asynchronously
        $emailService->sendOrderConfirmation(
            $this->orderId,
            $this->userEmail
        );
    }
}

Event Buffering Pattern

final class EventBuffer
{
    private array $bufferedEvents = [];

    #[OnEvent]
    public function bufferEvent(DomainEvent $event): void
    {
        $this->bufferedEvents[] = $event;
    }

    public function flush(EventDispatcher $dispatcher): void
    {
        foreach ($this->bufferedEvents as $event) {
            $dispatcher->dispatch($event);
        }

        $this->bufferedEvents = [];
    }
}

// Usage in transaction
try {
    $this->entityManager->beginTransaction();

    // Buffer events during transaction
    $this->eventBuffer->bufferEvent(new OrderCreatedEvent(/* ... */));
    $this->eventBuffer->bufferEvent(new InventoryReservedEvent(/* ... */));

    $this->entityManager->commit();

    // Flush events after successful commit
    $this->eventBuffer->flush($this->dispatcher);
} catch (\Exception $e) {
    $this->entityManager->rollback();
    // Events are not flushed on rollback
    throw $e;
}

Event Best Practices

1. Event Naming

✅ Good: Past tense, descriptive

OrderCreatedEvent
UserRegisteredEvent
PaymentCompletedEvent
InventoryReservedEvent

❌ Bad: Present/future tense, vague

CreateOrderEvent
RegisterUserEvent
CompletePayment
ReserveInventory

2. Event Granularity

✅ Focused Events:

final readonly class OrderCreatedEvent { /* ... */ }
final readonly class OrderShippedEvent { /* ... */ }
final readonly class OrderCancelledEvent { /* ... */ }

❌ God Events:

final readonly class OrderEvent
{
    public function __construct(
        public string $action, // 'created', 'shipped', 'cancelled'
        public Order $order
    ) {}
}

3. Immutability

✅ Readonly Events:

final readonly class UserUpdatedEvent
{
    public function __construct(
        public UserId $userId,
        public Email $newEmail
    ) {}
}

❌ Mutable Events:

final class UserUpdatedEvent
{
    public UserId $userId;
    public Email $newEmail;

    public function setEmail(Email $email): void
    {
        $this->newEmail = $email; // Bad: Events should be immutable
    }
}

4. Handler Independence

✅ Independent Handlers:

#[OnEvent]
public function sendEmail(OrderCreatedEvent $event): void
{
    // Self-contained - doesn't depend on other handlers
    $this->emailService->send(/* ... */);
}

#[OnEvent]
public function updateInventory(OrderCreatedEvent $event): void
{
    // Independent - no shared state with email handler
    $this->inventoryService->reserve(/* ... */);
}

❌ Coupled Handlers:

private bool $emailSent = false;

#[OnEvent(priority: 100)]
public function sendEmail(OrderCreatedEvent $event): void
{
    $this->emailService->send(/* ... */);
    $this->emailSent = true; // Bad: Shared state
}

#[OnEvent(priority: 50)]
public function logEmailSent(OrderCreatedEvent $event): void
{
    if ($this->emailSent) { // Bad: Depends on other handler
        $this->logger->info('Email sent');
    }
}

5. Error Handling

✅ Graceful Degradation:

#[OnEvent]
public function sendNotification(OrderCreatedEvent $event): void
{
    try {
        $this->notificationService->send(/* ... */);
    } catch (NotificationException $e) {
        // Log error but don't fail the entire event dispatch
        $this->logger->error('Notification failed', [
            'order_id' => $event->orderId->toString(),
            'error' => $e->getMessage()
        ]);
    }
}

6. Avoid Circular Events

❌ Circular Dependency:

#[OnEvent]
public function onOrderCreated(OrderCreatedEvent $event): void
{
    // Bad: Dispatching event from event handler can cause loops
    $this->eventBus->dispatch(new OrderProcessedEvent($event->orderId));
}

#[OnEvent]
public function onOrderProcessed(OrderProcessedEvent $event): void
{
    // Bad: Creates circular dependency
    $this->eventBus->dispatch(new OrderCreatedEvent(/* ... */));
}

✅ Use Command/Service Layer:

#[OnEvent]
public function onOrderCreated(OrderCreatedEvent $event): void
{
    // Good: Use service to perform additional work
    $this->orderProcessingService->processOrder($event->orderId);
}

7. Performance Considerations

Heavy Operations → Queue:

#[OnEvent]
public function generateInvoicePdf(OrderCreatedEvent $event): void
{
    // Heavy operation - push to queue
    $this->queue->push(
        JobPayload::immediate(
            new GenerateInvoiceJob($event->orderId)
        )
    );
}

Light Operations → Synchronous:

#[OnEvent]
public function logOrderCreation(OrderCreatedEvent $event): void
{
    // Light operation - execute immediately
    $this->logger->info('Order created', [
        'order_id' => $event->orderId->toString()
    ]);
}

Common Patterns

Event Sourcing Pattern

final class OrderEventStore
{
    #[OnEvent]
    public function appendEvent(DomainEvent $event): void
    {
        $this->eventStore->append([
            'event_type' => get_class($event),
            'event_data' => json_encode($event),
            'occurred_at' => $event->occurredAt->format('Y-m-d H:i:s'),
            'aggregate_id' => $event->getAggregateId()
        ]);
    }
}

Saga Pattern

final readonly class OrderSaga
{
    #[OnEvent(priority: 100)]
    public function onOrderCreated(OrderCreatedEvent $event): void
    {
        // Step 1: Reserve inventory
        $this->inventoryService->reserve($event->items);
    }

    #[OnEvent(priority: 90)]
    public function onInventoryReserved(InventoryReservedEvent $event): void
    {
        // Step 2: Process payment
        $this->paymentService->charge($event->orderId);
    }

    #[OnEvent(priority: 80)]
    public function onPaymentCompleted(PaymentCompletedEvent $event): void
    {
        // Step 3: Ship order
        $this->shippingService->ship($event->orderId);
    }
}

CQRS Pattern

// Command Side - Dispatches Events
final readonly class CreateOrderHandler
{
    public function handle(CreateOrderCommand $command): Order
    {
        $order = Order::create($command);
        $this->repository->save($order);

        $this->eventBus->dispatch(
            new OrderCreatedEvent($order)
        );

        return $order;
    }
}

// Query Side - Maintains Read Model
#[OnEvent]
public function updateOrderReadModel(OrderCreatedEvent $event): void
{
    $this->orderReadModel->insert([
        'order_id' => $event->orderId->toString(),
        'user_id' => $event->userId->toString(),
        'total' => $event->total->toDecimal(),
        'status' => 'created'
    ]);
}

Framework Integration

With Queue System

#[OnEvent]
public function queueHeavyTask(OrderCreatedEvent $event): void
{
    $this->queue->push(
        JobPayload::immediate(
            new ProcessOrderAnalyticsJob($event->orderId)
        )
    );
}

With Scheduler

#[OnEvent]
public function scheduleReminder(OrderCreatedEvent $event): void
{
    $this->scheduler->schedule(
        'send-order-reminder-' . $event->orderId,
        OneTimeSchedule::at(Timestamp::now()->addDays(3)),
        fn() => $this->emailService->sendReminder($event->orderId)
    );
}

With Cache System

#[OnEvent]
public function invalidateCache(OrderCreatedEvent $event): void
{
    $this->cache->forget(
        CacheTag::fromString("user_{$event->userId}")
    );
}

Summary

The Event System provides:

✅ Decoupled Architecture: Loose coupling via events
✅ Flexible Handling: Priority-based, propagation control
✅ Automatic Discovery: #[OnEvent] attribute registration
✅ Multiple Patterns: Domain events, application events, async processing
✅ Framework Integration: Works with Queue, Scheduler, Cache
✅ Testing Support: Easy to unit test and integration test
✅ Performance: Efficient handler execution with priority optimization

When to Use Events:

Decoupling domain logic from side effects (email, notifications)
Cross-module communication without tight coupling
Audit trail and event sourcing
Async processing of non-critical operations
CQRS and saga patterns

When NOT to Use Events:

Synchronous business logic requiring immediate results
Simple function calls (don't over-engineer)
Performance-critical paths (events have overhead)
Operations requiring transactional guarantees across handlers

23 KiB Raw Blame History

Event System

Overview

EventBus vs EventDispatcher

EventBus Interface

EventDispatcher Implementation

Implementation Relationship

Domain Events

What are Domain Events?

Creating Domain Events

Framework Lifecycle Events

ApplicationBooted

BeforeHandleRequest

AfterHandleRequest

Example: User Registration Event

Event Handler Registration

Attribute-Based Registration

Priority-Based Execution

Stop Propagation

Manual Handler Registration

Handler Discovery

Event Middleware

Custom Event Middleware

Middleware Pipeline

Validation Middleware

Async Event Processing

Queue-Based Async Handling

Event Buffering Pattern

Event Best Practices

1. Event Naming

2. Event Granularity

3. Immutability

4. Handler Independence

5. Error Handling

6. Avoid Circular Events

7. Performance Considerations

Common Patterns

Event Sourcing Pattern

Saga Pattern

CQRS Pattern

Framework Integration

With Queue System

With Scheduler

With Cache System

Summary

23 KiB

Raw Blame History