Action-Trigger und Event-Listener

Auf einen Blick

NextPDF löst Lebenszyklus-Events über ein PSR-14-kompatibles System in NextPDF\Event aus. Registrieren Sie einen Listener mit einer Priorität. Reagieren Sie auf das Erstellen eines Dokuments, eine neue Seite, das Laden einer Schrift, das Signieren, das Verschlüsseln, das Schreiben oder die Ausgabe. Stoppen Sie die Kette bei Bedarf.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Das Event-System besteht aus zwei öffentlichen Teilen. ListenerProvider ordnet einer Event-Klasse eine sortierte Liste von Listener-Callables zu. EventDispatcher durchläuft diese Liste und ruft jeden Listener in der Reihenfolge der Priorität auf. Beide Klassen sind final; erweitern Sie sie daher über Komposition statt durch Subklassenbildung.

Beide Klassen entsprechen PSR-14 über Duck-Typing. EventDispatcher::dispatch() entspricht der PSR-14-Signatur dispatch() und gibt das Event zurück, nachdem jeder Listener ausgeführt wurde. ListenerProvider::getListenersForEvent() entspricht der PSR-14-Provider-Signatur. NextPDF setzt das PSR-14-Paket nicht voraus; wenn Ihr Projekt es jedoch verwendet, passen die Interfaces trotzdem zusammen.

Für Extension-Autoren sind zwei Verhaltensweisen wichtig:

Wildcard-Listening. Um Listener aufzulösen, durchläuft der Provider die Elternklassen des Events und dessen Interfaces. Binden Sie einen Listener an die Basisklasse AbstractEvent, um jedes Lebenszyklus-Event zu beobachten. Binden Sie ihn an ein Interface, um eine ganze Familie abzufangen.
Priorität und Weitergabe. Listener mit höherer Priorität werden zuerst ausgeführt. Bei gleicher Priorität bleibt die Registrierungsreihenfolge erhalten. Jedes Event, das AbstractEvent erweitert, ist stoppbar. Ein Listener kann stopPropagation() aufrufen. Der Dispatcher überspringt dann die verbleibenden Listener.

Der Dispatcher verfügt über einen Fast-Path ohne Zusatzkosten. Wenn für eine Event-Klasse oder eine Elternklasse kein Listener gebunden ist, kehrt dispatch() sofort nach einer einzigen hasListeners()-Prüfung zurück.

Lebenszyklus-Events

Event	Namespace	Ausgelöst, wenn	Stabilität
`DocumentCreatedEvent`	`NextPDF\Event\Document`	Die Konstruktion eines Dokuments ist abgeschlossen	experimental
`PageAddedEvent`	`NextPDF\Event\Document`	Eine Seite ist vollständig initialisiert	experimental
`ContentRenderedEvent`	`NextPDF\Event\Content`	Inhalt wird auf eine Seite gerendert	experimental
`FontLoadedEvent`	`NextPDF\Event\Content`	Eine Schriftfamilie und ein Schriftstil werden zum ersten Mal geladen	experimental
`SignatureAppliedEvent`	`NextPDF\Event\Security`	Signatur-Bytes werden eingebettet	experimental
`EncryptionAppliedEvent`	`NextPDF\Event\Security`	Die Verschlüsselung wird konfiguriert	experimental
`PdfSerializedEvent`	`NextPDF\Event\Writer`	Die Serialisierung schließt ab	experimental
`DocumentOutputEvent`	`NextPDF\Event\Document`	Vor der Auslieferung der Ausgabe	experimental

Der Dispatcher, der Provider, das Marker-Interface und die Basisklasse sind stable (seit 3.0.0). Die Event-Payloads sind experimental. Ihre Konstruktorargumente und readonly-Eigenschaften können sich in einem Minor-Release ändern. Ein Patch-Release fügt nur hinzu. Berücksichtigen Sie diese Stabilitätsstufe, wenn Sie an die Namen der Payload-Eigenschaften binden.

API-Oberfläche

NextPDF\Event\ListenerProvider (stable, final):

Methode	Rückgabe	Zweck
`addListener(string $eventClass, callable $listener, int $priority = 0)`	`void`	Registriert einen Listener; eine höhere Priorität wird zuerst ausgeführt. Wirft bei einer leeren Klasse `InvalidConfigException`.
`getListenersForEvent(EventInterface $event)`	`list<callable>`	Löst Listener auf, einschließlich der Eltern- und Interface-Registrierungen.
`hasListeners(string $eventClass)`	`bool`	Prüfung ohne Overhead über die Klassenhierarchie hinweg.
`getListenerCount(string $eventClass)`	`int`	Zählt nur die direkten Registrierungen.
`clearListeners()`	`void`	Setzt den Provider zurück.

NextPDF\Event\EventDispatcher (stable, final):

Methode	Rückgabe	Zweck
`dispatch(EventInterface $event)`	`EventInterface`	Ruft Listener in der Reihenfolge der Priorität auf; respektiert den Propagation-Stopp; gibt das Event zurück.
`getListenerProvider()`	`ListenerProvider`	Greift auf den Provider zu, um zur Laufzeit Listener hinzuzufügen.

Dokumente, die Events auslösen, verwenden NextPDF\Event\EventAwareDocumentTrait. Seine Methode setEventDispatcher() bindet einen Dispatcher in ein Dokument ein. Ohne Dispatcher bleibt jeder Dispatch-Helfer wirkungslos.

Codebeispiel — Schnellstart

<?php

declare(strict_types=1);

use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;
use NextPDF\Event\Security\SignatureAppliedEvent;

$listeners = new ListenerProvider();
$listeners->addListener(
    SignatureAppliedEvent::class,
    static function (SignatureAppliedEvent $event): void {
        \error_log("Signed at level {$event->signatureLevel} by {$event->signerName}");
    },
    priority: 100,
);

$dispatcher = new EventDispatcher($listeners);

Codebeispiel — Produktion

Dies ist ein Audit-Listener für die Produktion. Er verwendet eine hohe Priorität, damit er zuerst ausgeführt wird, protokolliert strukturiert und ergänzt der Vollständigkeit halber einen Catch-all-Listener auf der Basisklasse.

<?php

declare(strict_types=1);

use NextPDF\Event\AbstractEvent;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;
use NextPDF\Event\Security\EncryptionAppliedEvent;
use NextPDF\Event\Security\SignatureAppliedEvent;
use Psr\Log\LoggerInterface;

final class SecurityAuditSubscriber
{
    public function __construct(private readonly LoggerInterface $logger) {}

    public function register(ListenerProvider $listeners): EventDispatcher
    {
        $listeners->addListener(
            SignatureAppliedEvent::class,
            function (SignatureAppliedEvent $event): void {
                $this->logger->info('signature.applied', [
                    'level'  => $event->signatureLevel,
                    'signer' => $event->signerName,
                ]);
            },
            priority: 1000,
        );

        $listeners->addListener(
            EncryptionAppliedEvent::class,
            function (EncryptionAppliedEvent $event): void {
                $this->logger->info('encryption.applied', [
                    'algorithm' => $event->algorithm,
                ]);
            },
            priority: 1000,
        );

        // Catch-all: observe every lifecycle event for trace completeness.
        $listeners->addListener(
            AbstractEvent::class,
            fn (AbstractEvent $event): mixed
                => $this->logger->debug('lifecycle', ['event' => $event->getEventName()]),
            priority: -1000,
        );

        return new EventDispatcher($listeners);
    }
}

Grenzfälle & Stolperfallen

Finale Klassen. EventDispatcher und ListenerProvider sind final. Nutzen Sie Komposition statt Subklassenbildung.
Eine leere Event-Klasse wirft. addListener('', ...) wirft InvalidConfigException. Übergeben Sie immer eine Class-String-Konstante.
Wildcard-Kosten. Ein Listener auf AbstractEvent wird für jedes Event ausgelöst. Geben Sie Catch-all-Listenern eine niedrige Priorität. Halten Sie sie leichtgewichtig.
Mutation der Ausgabe. DocumentOutputEvent enthält die PDF-Bytes. Die Engine liest sie nach dem Dispatch zurück. Wenn Sie diese Bytes ändern, erhalten Sie weitreichende Kontrolle, tragen aber auch ein echtes Risiko. Ein falscher Byte-Offset beschädigt das PDF und kann eine Signatur brechen. Beobachten Sie lieber, es sei denn, Sie verantworten das Ergebnis im Hinblick auf Determinismus und Signaturen.
Kein Dispatcher, keine Events. Ein Dokument, bei dem kein Dispatcher über EventAwareDocumentTrait gesetzt wurde, löst keine Events aus. Dies ist der beabsichtigte Pfad ohne Zusatzkosten. Es ist kein Einrichtungsfehler.

Performance

Der Fast-Path besteht aus einer einzigen hasListeners()-Prüfung entlang der Elternkette. Ohne Listener ist das Dispatchen nahezu ohne Overhead. Der Provider cacht die sortierte Listener-Liste pro Event-Klasse. Er leert diesen Cache nur bei einer Änderung. Halten Sie Listener nicht-blockierend. Sie laufen inline auf dem Render-Pfad.

Sicherheitshinweise

SignatureAppliedEvent und EncryptionAppliedEvent sind die Audit-Anker. Registrieren Sie Listener mit hoher Priorität, um das Signieren und Verschlüsseln in einen manipulationssicheren Speicher zu protokollieren. Stoppen Sie die Kette bei einem Sicherheits-Event nicht, es sei denn, Sie möchten spätere Listener stummschalten. Wenn Sie sie stoppen, können nachgelagerte Audit-Hooks stillschweigend abgeschaltet werden.

Konformität

Auf dieser Seite werden keine normativen Aussagen über die PSR-14-Kompatibilität hinaus getroffen, die rein per Duck-Typing besteht und das PSR-14-Paket nicht voraussetzt.

Kommerzieller Kontext

NextPDF Enterprise liefert auditierte Listener für Signatur- und Verschlüsselungs-Events, die ein manipulationssicheres Audit-Log speisen. Der Listener-Vertrag ist die öffentliche Event-API, sodass Ihre eigenen Listener mit den Enterprise-Listenern auf demselben Provider koexistieren.