michaelschiemer/backups/docs-backup-20250731125004/framework/analytics/migration.md

# Analytics-Framework: Migrationsleitfaden

## Von Version 1.x zu 2.x

### Überblick der Änderungen

Die Version 2.x des Analytics-Frameworks führt mehrere wichtige Verbesserungen und Änderungen ein:

- **Typsicherheit**: Neue Event-Klassen statt Arrays
- **Dependency Injection**: Verbesserte Integration mit dem Container
- **Storage-Abstraktion**: Flexiblere Speichermethoden
- **Fehlerbehandlung**: Robustere Exception-Handling
- **Middleware-System**: Standardisierte Middleware-Pipeline

### Notwendige Migrationsschritte

#### 1. Konfiguration aktualisieren

**Alt (1.x):**
```php
return [
    'enabled' => true,
    'auto_flush' => true,
    'batch_size' => 50,
    'storage' => 'file',
    'storage_path' => '/pfad/zum/speicher',
];
```

**Neu (2.x):**
```php
return [
    'enabled' => true,
    'auto_flush' => true,
    'batch_size' => 50,
    'storage_driver' => 'file',  // Umbenannt
    'storage_config' => [        // Neue Struktur
        'path' => '/pfad/zum/speicher',
    ],
    'excluded_paths' => [],      // Neue Option
    'excluded_user_agents' => [], // Neue Option
    'max_file_size' => 10 * 1024 * 1024, // Neue Option
];
```

#### 2. Event-Objekte (falls genutzt)

**Alt (1.x):**
```php
$analytics->track('custom_event', ['property' => 'value']);
```

**Neu (2.x) - Option 1 (abwärtskompatibel):**
```php
// Weiterhin unterstützt
$analytics->track('custom_event', ['property' => 'value']);
```

**Neu (2.x) - Option 2 (typsicher):**
```php
use App\Framework\Analytics\Events\CustomEvent;

$event = new CustomEvent('wert', ['weitere' => 'daten']);
$analytics->trackEvent($event);
```

#### 3. Eigene Storage-Provider

**Alt (1.x):**
```php
class CustomStorage implements StorageInterface
{
    public function store(array $events): void
    {
        // Implementation
    }

    public function retrieve(array $filters = []): array
    {
        // Implementation
    }

    public function clear(): void
    {
        // Implementation
    }
}
```

**Neu (2.x):**
```php
use Psr\Log\LoggerInterface;

class CustomStorage implements StorageInterface
{
    public function __construct(
        private readonly array $config,
        private readonly LoggerInterface $logger
    ) {}

    public function store(array $events): void
    {
        try {
            // Implementation mit Fehlerbehandlung
        } catch (\Exception $e) {
            $this->logger->error('Storage error', ['exception' => $e]);
            throw new StorageException('Failed to store events', 0, $e);
        }
    }

    // Andere Methoden analog
}
```

#### 4. Middleware anpassen

**Alt (1.x):**
```php
$analyticsManager->addMiddleware(function(array $event) {
    // Verarbeitung
    return $event;
});
```

**Neu (2.x) - Option 1 (abwärtskompatibel):**
```php
// Weiterhin unterstützt
$analyticsManager->addMiddleware(function(array $event) {
    // Verarbeitung
    return $event;
});
```

**Neu (2.x) - Option 2 (typsicher):**
```php
use App\Framework\Analytics\Middleware\AnalyticsMiddleware;
use App\Framework\Analytics\Events\AnalyticsEvent;

class CustomMiddleware implements AnalyticsMiddleware
{
    public function process(AnalyticsEvent $event): ?AnalyticsEvent
    {
        // Verarbeitung
        return $event;
    }
}

// Registrierung
$analyticsManager->addMiddleware(new CustomMiddleware());
```

### Automatisierte Tests

Führen Sie die folgenden Tests durch, um sicherzustellen, dass die Migration erfolgreich war:

```bash
php console test:run --group=analytics
```

Weitere Informationen zur Migration finden Sie in den Änderungsprotokollen im Quellcode-Repository.