# TerraFlowCMS Event-System

Das TerraFlowCMS Event-System ermöglicht es Plugins und der Anwendung selbst, auf verschiedene Aktionen zu reagieren. Es ist feingranular aufgebaut und bietet eine umfassende API für Event-Listener.

## Übersicht

Das Event-System besteht aus folgenden Komponenten:

- **BaseEvent**: Basis-Klasse für alle Events
- **EventDispatcherService**: Service für das Dispatchen von Events
- **EventAwarePluginInterface**: Interface für Event-bewusste Plugins
- **AbstractEventAwarePlugin**: Abstrakte Basis-Klasse für Plugins

## Event-Kategorien

### User Events
- `UserLoginEvent`: Wird ausgelöst, wenn sich ein User einloggt
- `UserLogoutEvent`: Wird ausgelöst, wenn sich ein User ausloggt
- `UserRegistrationEvent`: Wird ausgelöst, wenn sich ein User registriert
- `UserProfileUpdateEvent`: Wird ausgelöst, wenn ein User sein Profil aktualisiert

### Content Events
- `PageCreateEvent`: Wird ausgelöst, wenn eine neue Seite erstellt wird
- `PageUpdateEvent`: Wird ausgelöst, wenn eine Seite aktualisiert wird
- `PageDeleteEvent`: Wird ausgelöst, wenn eine Seite gelöscht wird
- `MediaUploadEvent`: Wird ausgelöst, wenn eine Datei hochgeladen wird
- `MediaDeleteEvent`: Wird ausgelöst, wenn eine Datei gelöscht wird

### System Events
- `CacheClearEvent`: Wird ausgelöst, wenn der Cache geleert wird
- `BackupCreateEvent`: Wird ausgelöst, wenn ein Backup erstellt wird
- `SettingsUpdateEvent`: Wird ausgelöst, wenn die Einstellungen aktualisiert werden

### Plugin Events
- `PluginInstallEvent`: Wird ausgelöst, wenn ein Plugin installiert wird
- `PluginActivateEvent`: Wird ausgelöst, wenn ein Plugin aktiviert wird
- `PluginDeactivateEvent`: Wird ausgelöst, wenn ein Plugin deaktiviert wird

### API Events
- `ApiRequestEvent`: Wird ausgelöst, wenn eine API-Anfrage eingeht
- `ApiResponseEvent`: Wird ausgelöst, wenn eine API-Antwort gesendet wird

### Admin Events
- `AdminActionEvent`: Wird ausgelöst, wenn eine Admin-Aktion durchgeführt wird

## Event-Listener erstellen

### Plugin-Event-Listener

```php
<?php

namespace MyPlugin;

use TerraFlow\Plugin\AbstractEventAwarePlugin;
use TerraFlow\Event\Content\PageCreateEvent;
use TerraFlow\Event\User\UserRegistrationEvent;

class MyPlugin extends AbstractEventAwarePlugin
{
    public function getEventListeners(): array
    {
        return [
            PageCreateEvent::getEventName() => [$this, 'onPageCreate'],
            UserRegistrationEvent::getEventName() => [$this, 'onUserRegistration'],
        ];
    }

    public function onPageCreate(PageCreateEvent $event): void
    {
        // Reaktion auf Seiten-Erstellung
        $page = $event->getPage();
        // ... Plugin-Logik
    }

    public function onUserRegistration(UserRegistrationEvent $event): void
    {
        // Reaktion auf User-Registrierung
        $user = $event->getUser();
        // ... Plugin-Logik
    }
}
```

### Service-Event-Listener

```php
<?php

namespace TerraFlow\EventListener;

use TerraFlow\Event\Content\PageCreateEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: PageCreateEvent::getEventName())]
class PageCreateListener
{
    public function __invoke(PageCreateEvent $event): void
    {
        // Reaktion auf Seiten-Erstellung
    }
}
```

## Event-Dispatcher Service

Der `EventDispatcherService` bietet erweiterte Funktionalitäten:

```php
// Event dispatched
$event = new PageCreateEvent($page);
$this->eventDispatcher->dispatch($event);

// Asynchrones Event
$this->eventDispatcher->dispatchAsync($event);

// Event nur dispatched wenn Listener vorhanden
$this->eventDispatcher->dispatchIfHasListeners($event);

// Batch-Dispatch
$events = [$event1, $event2, $event3];
$this->eventDispatcher->dispatchBatch($events);
```

## Event-Kontext

Events können zusätzlichen Kontext enthalten:

```php
$event = new PageCreateEvent($page, [
    'source' => 'admin_panel',
    'template' => 'custom_template'
]);
```

## Event-Prioritäten

Plugins können Event-Prioritäten definieren:

```php
public function getEventPriority(): int
{
    return 100; // Höhere Zahlen = höhere Priorität
}
```

## Asynchrone Events

Plugins können asynchrone Event-Verarbeitung unterstützen:

```php
public function supportsAsyncEvents(): bool
{
    return true;
}
```

## Event-Statistiken

```php
$stats = $this->eventDispatcher->getEventStats();
// Gibt Statistiken über registrierte Events zurück
```

## Best Practices

1. **Event-Namen**: Verwende aussagekräftige Event-Namen
2. **Kontext**: Füge relevante Kontext-Informationen hinzu
3. **Fehlerbehandlung**: Behandle Fehler in Event-Listenern graceful
4. **Performance**: Verwende asynchrone Events für zeitaufwändige Operationen
5. **Logging**: Logge wichtige Events für Debugging und Monitoring

## Migration von altem Event-System

Das neue Event-System ist rückwärtskompatibel. Bestehende Events werden weiterhin unterstützt:

```php
// Altes Event (deprecated)
$event = new MediaUploadEvent($file);

// Neues Event
$event = new \TerraFlow\Event\Content\MediaUploadEvent($media, $file);
```

## Plugin-Entwicklung

Für Plugin-Entwickler bietet das Event-System:

- **Einfache Integration**: Erweitere `AbstractEventAwarePlugin`
- **Automatische Registrierung**: Event-Listener werden automatisch registriert
- **Flexible Reaktionen**: Reagiere auf verschiedene Event-Typen
- **Kontext-Zugriff**: Zugriff auf Event-Kontext und Metadaten
- **Prioritäts-System**: Kontrolle über Event-Verarbeitungsreihenfolge

## Debugging

Events werden automatisch geloggt. Verwende die Logs, um Event-Flows zu verfolgen:

```bash
tail -f var/log/dev.log | grep "Event dispatched"
```

## Erweiterte Features

- **Event-Filtering**: Filtere Events basierend auf Kontext
- **Event-Transformation**: Transformiere Events vor der Verarbeitung
- **Event-Chaining**: Verkette Events für komplexe Workflows
- **Event-Middleware**: Füge Middleware für Event-Verarbeitung hinzu