English Version

Zurück zur Übersicht

Matomo Analytics: Technische Details

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Ablauf

Alle Aufrufer, also Storefront-Hooks und Shop API, fragen dieselbe Stelle: den Resolver für die Tracking-Konfiguration. Er liest die Einstellungen des Channels und prüft sie mit einer einzigen Gültigkeitsprüfung. Ein unvollständiger Eintrag verhält sich dadurch überall wie ein ausgeschalteter, und kein Aufrufer leitet seine eigene Vorstellung von „ausreichend konfiguriert“ ab.

graph TD
    A["Twig-Hook oder Shop API Anfrage"] --> B["Resolver der Tracking-Konfiguration"]
    B --> C["Einstellungen des Channels aus der Datenbank"]
    C --> D{"Zeile vorhanden?"}
    D -->|"Nein"| N["null: nichts ausliefern / 404"]
    D -->|"Ja"| E{"Hauptschalter an, HTTPS-URL, Site-ID größer 0?"}
    E -->|"Nein"| N
    E -->|"Ja"| F{"Klaro-Gating an?"}
    F -->|"Nein"| G["Skript direkt ausliefern"]
    F -->|"Ja"| H["Skript als text/plain blockiert + Einwilligungs-Brücke"]
    H --> I["Klaro schaltet nach Zustimmung frei"]

Der Resolver merkt sich das Ergebnis pro Channel für die Dauer der Anfrage, auch wenn die Hooks mehrfach fragen. Pro Channel und Anfrage gibt es also eine Datenbankabfrage. Der Cache wird beim Zurücksetzen des Kernels geleert (wichtig für langlebige Worker).

Schlägt der Datenbankzugriff fehl, etwa weil die Tabelle noch fehlt, gibt der Resolver null zurück und schreibt eine Warnung in den Log-Kanal mmd_matomo. Dieses Ergebnis wird nicht zwischengespeichert: Ist die Datenbank später wieder da, wird wieder getrackt.

Sicherheit der Ausgabe

• Die Matomo-URL wird vor der Ausgabe validiert (HTTPS, keine Zeichen, die aus dem Inline-Skript ausbrechen könnten). Die JavaScript-Maskierung beim Rendern ist eine zweite Sicherung, nicht die erste.
• Namen, SKUs, Preise und Mengen gehen durch json_encode mit JSON_HEX_TAG, damit ein Produktname kein </script> einschleusen kann.

Plugin-Struktur

src/
├── Api/                  Shop-API-Ressource und Provider
├── Command/              Setup-Befehl
├── DependencyInjection/  Extension (Mapping, Hooks, Grid, Migrationen), leere Configuration
├── Entity/               ChannelSettings und Interface
├── EventListener/        Klaro-Dienst beim Speichern anlegen
├── Form/Type/            Formular der Channel-Einstellungen
├── Klaro/                Verfügbarkeit, Katalog-Schnittstelle, Provisionierung
├── Menu/                 Sidebar-Eintrag
├── Migrations/           Tabelle anlegen
├── Settings/             Repository
├── Tracking/             Konfiguration, Resolver, Code-Renderer, Bestelldaten
└── Twig/                 Twig-Funktionen
config/
├── grids/                Grid der Einstellungen
├── routes/               Admin-Routen
├── twig_hooks/           Hooks für Admin, Storefront und E-Commerce
└── services.php          Service-Definitionen
templates/                Tracking-Skript, E-Commerce-Snippets, Admin-Titel
translations/             Deutsch und Englisch

Datenbank

Das Plugin legt genau eine Tabelle an: mmd_sylius_matomo_channel_settings, mit einer Zeile pro Channel. Die Zuordnung läuft über den Channel-Code (Text), nicht über einen Fremdschlüssel. Ein eindeutiger Index auf channel_code erzwingt eine Zeile pro Channel.

Alle Spalten sind NOT NULL. Die Standardwerte in der Tabelle setzt die Entity beim Anlegen einer Zeile, die Datenbank selbst kennt keine DEFAULT-Werte. Schreibst du Zeilen am Plugin vorbei in die Tabelle, musst du alle Spalten selbst füllen.

Die Admin-Routen heißen mmd_sylius_matomo_integration_plugin_admin_channel_settings_index, _create, _update und _delete, der Pfad ist /<admin-pfad>/matomo-channel-settings (der Admin-Pfad kommt aus dem Parameter sylius_admin.path_name).

Die Entity-Validierung ist bewusst locker: Ein unvollständiger Eintrag lässt sich speichern, ob er tatsächlich trackt, entscheidet allein die Gültigkeitsprüfung zur Laufzeit.

Die Migration liegt im Namespace Mmd\SyliusMatomoIntegrationPlugin\Migrations und nicht im Standard-Namespace DoctrineMigrations, damit sie nicht mit den Migrationen deines Projekts kollidiert. Sie setzt voraus, dass die Sylius-Core-Migrationen ausgeführt sind.