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):

return [
    'enabled' => true,
    'auto_flush' => true,
    'batch_size' => 50,
    'storage' => 'file',
    'storage_path' => '/pfad/zum/speicher',
];

Neu (2.x):

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):

$analytics->track('custom_event', ['property' => 'value']);

Neu (2.x) - Option 1 (abwärtskompatibel):

// Weiterhin unterstützt
$analytics->track('custom_event', ['property' => 'value']);

Neu (2.x) - Option 2 (typsicher):

use App\Framework\Analytics\Events\CustomEvent;

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

3. Eigene Storage-Provider

Alt (1.x):

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):

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):

$analyticsManager->addMiddleware(function(array $event) {
    // Verarbeitung
    return $event;
});

Neu (2.x) - Option 1 (abwärtskompatibel):

// Weiterhin unterstützt
$analyticsManager->addMiddleware(function(array $event) {
    // Verarbeitung
    return $event;
});

Neu (2.x) - Option 2 (typsicher):

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:

php console test:run --group=analytics

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