feat: implement event-driven module communication

[Chemaclass]

TL;DR

Adds EventBus and ModuleEvent infrastructure to enable loose coupling between modules through event-driven architecture, improving modularity and testability.

Summary

• EventBus for publishing and subscribing to module events with type-safe listener registration
• ModuleEvent base class with metadata support for custom event data
• Comprehensive documentation with practical examples and usage patterns
• Full test coverage for event bus functionality and module events

Key Features

Loose Coupling: Modules can communicate without direct dependencies through event-driven patterns

Type Safety: Strongly typed event handling with generics for compile-time safety

Metadata Support: Attach arbitrary data to events for flexible event payloads

Listener Management: Subscribe/unsubscribe event listeners dynamically at runtime

Testability: Easy to mock and test event-driven interactions in isolation

Use Cases

• Module lifecycle events (initialization, shutdown, configuration changes)
• Cross-module notifications without tight coupling
• Decoupled feature communication between bounded contexts
• Event sourcing patterns for audit trails and debugging
• Plugin and extension systems

Example Usage

use Gacela\Framework\Event\EventBus;
use Gacela\Framework\Event\ModuleEvent;

// Subscribe to events
EventBus::subscribe('user.created', function(ModuleEvent $event) {
    $userId = $event->getMetadata('user_id');
    // Handle user creation
});

// Publish events
EventBus::publish(new ModuleEvent('user.created', [
    'user_id' => 123,
    'timestamp' => time(),
]));