michaelschiemer/docs/framework/analytics/README.md

Analytics-Modul Dokumentation

Übersicht

Das Analytics-Modul ist ein internes Tracking- und Analysesystem, das ohne externe Abhängigkeiten Benutzeraktivitäten, Systemereignisse und Leistungsdaten erfasst und analysiert.

Kernkomponenten

Analytics (Analytics.php)

Die Hauptklasse, die als zentraler Einstiegspunkt für das Tracking von Events dient.

Hauptfunktionen:

• track(): Zeichnet ein generisches Event auf
• page(): Spezifisch für Seitenaufrufe
• user(): Verfolgt Benutzeridentifikation
• performance(): Erfasst Leistungsmetriken
• error(): Protokolliert Fehler und Ausnahmen

AnalyticsManager (AnalyticsManager.php)

Verwaltet die Verarbeitung und Speicherung von Events.

Hauptfunktionen:

• track(): Verarbeitet Events und wendet Middleware an
• addMiddleware(): Fügt Verarbeitungsfunktionen hinzu
• flush(): Schreibt gepufferte Events in den Speicher

StorageInterface und FileStorage

Das Interface definiert die Speichermethoden, FileStorage implementiert die Speicherung in Dateien.

Hauptoperationen:

• store(): Speichert Events
• retrieve(): Ruft Events mit Filtern ab
• clear(): Löscht alle gespeicherten Daten

AnalyticsInitializer (AnalyticsInitializer.php)

Konfiguriert und initialisiert den Analytics-Service beim Anwendungsstart.

Konfigurationsoptionen:

• Aktivierung/Deaktivierung
• Auto-Flush und Batch-Größe
• Storage-Typ und Pfad

AnalyticsMiddleware (AnalyticsMiddleware.php)

HTTP-Middleware zum automatischen Tracking von Requests und Responses.

AnalyticsDashboard (AnalyticsDashboard.php)

Stellt Methoden für Datenanalyse und -aggregation bereit:

• getEventStats(): Ereignisstatistiken
• getTopPages(): Meistbesuchte Seiten
• getUserStats(): Benutzerstatistiken
• getErrorStats(): Fehlerstatistiken
• getPerformanceStats(): Leistungsmetriken

Events

Vordefinierte Event-Typen:

• AnalyticsEvent: Basis-Event-Klasse
• PageViewEvent: Speziell für Seitenaufrufe

Controllers

AdminAnalyticsController: Stellt das Admin-Dashboard bereit mit:

• Übersichtsseite
• Seitenstatistiken
• Fehlerstatistiken
• Leistungsstatistiken

Console

AnalyticsClearCommand: Konsolenbefehl zum Löschen von Analytics-Daten.

Konfiguration

Die Konfiguration erfolgt in src/Config/analytics.php mit folgenden Optionen:

return [
    'enabled' => true,           // Aktiviert/deaktiviert das Tracking
    'auto_flush' => true,         // Automatisches Speichern nach Batch-Größe
    'batch_size' => 50,           // Anzahl Events pro Batch
    'storage' => 'file',          // Storage-Backend
    'storage_path' => '...',      // Speicherpfad
    'anonymize_ip' => true,       // IP-Anonymisierung
    'track_events' => [...]       // Zu trackende Events
];

Verwendung

Basis-Tracking

// Event tracken
$analytics->track('button_click', ['button' => 'signup']);

// Seitenaufruf tracken
$analytics->page('/dashboard', ['section' => 'analytics']);

// Benutzer identifizieren
$analytics->user('user123', ['plan' => 'premium']);

Middleware einrichten

$this->addMiddleware(App\Framework\Analytics\AnalyticsMiddleware::class);

Eigene Middleware hinzufügen

$analyticsManager->addMiddleware(function(array $event) {
    // Daten verarbeiten oder filtern
    return $event;
});

Datenschutz

Das System bietet integrierte Funktionen zur Anonymisierung personenbezogener Daten:

• IP-Adressen-Anonymisierung (letztes Oktett wird entfernt)
• Konfigurierbare Filterung sensibler Daten durch Middleware

Erweiterbarkeit

Eigene Storage-Provider

Implementieren Sie das StorageInterface für benutzerdefinierte Speicherlösungen:

class CustomStorage implements StorageInterface
{
    public function store(array $events): void { /* ... */ }
    public function retrieve(array $filters = []): array { /* ... */ }
    public function clear(): void { /* ... */ }
}

Event-Typen erweitern

Erstellen Sie benutzerdefinierte Event-Klassen, die von AnalyticsEvent erben:

class CustomEvent extends AnalyticsEvent
{
    public function __construct(string $customData, array $additionalProps = [])
    {
        parent::__construct('custom_event', 
            array_merge(['custom_data' => $customData], $additionalProps));
    }
}