> For the complete documentation index, see [llms.txt](https://docs.momocode.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.momocode.de/shopware-6/admin-aktivitaetsprotokoll/5.-erweiterung.md).

# 5. Erweiterung für Entwickler

Das Admin Aktivitätsprotokoll stellt eine öffentliche PHP-Extension-API bereit, mit der Entwickler eigene Entitäten für die Protokollierung registrieren können. Registrierte Entitäten erscheinen automatisch in der Plugin-Konfiguration und werden vollständig in der Protokollierung erfasst.

## Interface implementieren

Erstellen Sie eine Klasse, die `TrackableEntityProviderInterface` implementiert:

```php
use Momocode\MomoAdminActivityLog\Extension\TrackableEntityProviderInterface;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityWriteResult;

class MyCustomEntityProvider implements TrackableEntityProviderInterface
{
    public function getEntityName(): string
    {
        // DAL-Entitätsname (entspricht dem Tabellennamen)
        return 'my_custom_entity';
    }

    public function getLabel(): string
    {
        // Lesbarer Name, der in der Plugin-Konfiguration angezeigt wird
        return 'Meine benutzerdefinierte Entität';
    }

    public function resolveDisplayName(string $entityId, EntityWriteResult $writeResult, Context $context): ?string
    {
        // Optional: lesbaren Anzeigenamen für einen Protokolleintrag zurückgeben.
        // Wird aufgerufen, wenn ein Eintrag angelegt wird.
        // Gibt null zurück, wenn kein Name aufgelöst werden kann (Fallback auf die ID).
        return null;
    }

    public function getAdminRoute(): ?string
    {
        // Optional: Vue-Router-Route zur Detailseite der Entität.
        // Wird für Deep-Links in der Protokoll-Listenansicht verwendet.
        // Format: 'sw.my.custom.entity.detail'
        // Gibt null zurück, wenn keine Detailseite vorhanden ist.
        return null;
    }
}
```

## Service registrieren

Registrieren Sie den Provider in Ihrer `services.xml` mit dem Tag `momo.activity_log.entity_provider`:

```xml
<service id="MyVendor\MyPlugin\ActivityLog\MyCustomEntityProvider">
    <tag name="momo.activity_log.entity_provider" entity="my_custom_entity"/>
</service>
```

Das ist alles – der Compiler Pass des Plugins registriert den Provider automatisch. Beim nächsten Container-Build wird die Entität in die Protokollierung aufgenommen.

## Ergebnis

Nach der Registrierung:

* Erscheint die Entität in der Plugin-Konfiguration unter **Überwachte Entitäten** und kann dort aktiviert oder deaktiviert werden
* Werden alle Schreibvorgänge auf diese Entität automatisch protokolliert, sobald sie in der Konfiguration ausgewählt ist
* Werden Anzeigenamen (sofern `resolveDisplayName()` implementiert) in der Listenansicht angezeigt
* Werden Deep-Links (sofern `getAdminRoute()` implementiert) in der Listenansicht als klickbare Links gerendert

## Lesbare Werte für Referenzfelder (optional)

Referenzfelder Ihrer Entität (Fremdschlüssel, Many-to-Many-Verknüpfungen, ID-Listen) werden automatisch anhand der DAL-Definition erkannt. Ihre Änderungen werden als `Name (ID)` gespeichert, zum Beispiel `Shopware AG (019c36d8b73f70a2b5907a62f57cb152)`. Kann kein Name ermittelt werden, wird nur die ID gespeichert.

Passt die automatische Erkennung nicht (zum Beispiel bei einer ID in einem einfachen Text- oder JSON-Feld), kann Ihr Provider zusätzlich `ReferenceFieldProviderInterface` implementieren:

```php
use Momocode\MomoAdminActivityLog\Extension\ReferenceFieldProviderInterface;
use Momocode\MomoAdminActivityLog\Extension\TrackableEntityProviderInterface;
use Shopware\Core\Framework\Context;

class MyCustomEntityProvider implements TrackableEntityProviderInterface, ReferenceFieldProviderInterface
{
    // ... Methoden von TrackableEntityProviderInterface ...

    public function getReferenceFields(): array
    {
        // Feldname (Property- oder Spaltenname) => referenzierter DAL-Entitätsname.
        // Deklarationen haben für dasselbe Feld Vorrang vor der automatischen Erkennung.
        return [
            'ownerId' => 'customer',
            'legacyManufacturerRef' => 'product_manufacturer',
        ];
    }

    public function resolveReferenceNames(string $fieldName, string $referencedEntity, array $ids, Context $context): array
    {
        // Optional: [ID => lesbarer Name] für einige oder alle IDs zurückgeben.
        // Wird pro Feld und Request höchstens einmal mit allen gesammelten IDs aufgerufen - laden Sie die Namen mit einer Abfrage.
        // Nicht zurückgegebene IDs werden über die Standard-Namensauflösung des Plugins ermittelt.
        return [];
    }
}
```

* Die Registrierung (Service-Tag) ändert sich nicht.
* Provider, die das Interface nicht implementieren, funktionieren unverändert weiter.
* Exceptions aus `resolveReferenceNames()` werden abgefangen; stattdessen greift die Standard-Namensauflösung.
* Deaktiviert der Händler in der Plugin-Konfiguration **Lesbare Namen für verknüpfte Datensätze speichern**, wird keine der beiden Methoden aufgerufen und es werden nur IDs gespeichert.
* Namen werden beim Schreiben des Protokolleintrags ermittelt. Bestehende Einträge werden nicht verändert.
* Verknüpfungen (One-to-Many und Many-to-Many) Ihrer registrierten Entität erscheinen automatisch in der Plugin-Konfiguration unter **Ausgeschlossene Verknüpfungen**. Händler können dort störende Verknüpfungen vom Protokoll ausschließen; ein zusätzlicher Code ist dafür nicht nötig.

## Hinweise

* Die Methoden `resolveDisplayName()` und `getAdminRoute()` sind optional. Wenn sie `null` zurückgeben, zeigt das Plugin die Entitäts-ID als Klartext an.
* Das Interface befindet sich im Namespace `Momocode\MomoAdminActivityLog\Extension`.
* Der Service-Tag `momo.activity_log.entity_provider` muss exakt so geschrieben sein – andernfalls wird der Provider vom Compiler Pass nicht erkannt.