PDF-Lebenszyklusereignisse beim Einbetten von NextPDF Connect beobachten

Auf einen Blick

Sie können PDF-Lebenszyklusereignisse beobachten und darauf reagieren — Dokument erstellt, Seite hinzugefügt, Schriftart geladen, Signatur angewendet, Ausgabe erzeugt — ohne von der Dokumentklasse abzuleiten. Dies ist eine Funktion der Bibliothekseinbettung, kein Connect-Tool. Die Remote-Transportoberfläche von Connect (MCP / REST / gRPC) stellt kein Event-Listener-Tool bereit; daher beobachten Sie Ereignisse nur, wenn Sie die Engine prozessintern hosten und einen Dispatcher einbinden. Diese Seite legt diese Grenze und das prozessinterne Muster klar offen, damit Aufrufer nicht mit einem Remote-Hook rechnen.

Installation

composer require nextpdf/server

Dieses Muster gilt, wenn Ihre Anwendung die Engine einbettet und sie direkt in PHP aufruft, etwa in einem benutzerdefinierten Server-Host. Nutzen Sie bei einem Remote-Transport stattdessen Telemetrie und Observability an der Transportgrenze.

Konzeptioneller Überblick

Die Engine löst Ereignisse über einen Dispatcher im PSR-14-Stil aus. Sie erstellen einen Listener-Provider und einen Dispatcher, registrieren Listener pro Ereignisklasse und weisen den Dispatcher anschließend einem Dokument zu. Von da an werden Ereignisse beim Erstellen des Dokuments automatisch ausgelöst. Wenn kein Dispatcher angehängt ist, verursacht das Ereignissystem keinerlei Overhead, da jeder Dispatch-Punkt nur eine null-Prüfung durchführt. Klassen werden über die Autoload-Klasse→Datei-Zuordnung aufgelöst (PSR-4 §3), und der gesamte Beispielcode deklariert strikte Typen und folgt dem Coding-Standard (PSR-12 §2.1).

API-Oberfläche

Es gibt kein Connect-Tool für Event-Hooks. Der Tool-Katalog ist der maßgebliche Katalog, und er führt keines auf. Die prozessinterne Oberfläche besteht aus den Ereignisklassen der Engine (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) sowie dem Listener-Provider und dem Dispatcher. Die über einen Transport verfügbaren Tools hängen von der installierten Stufe ab; Event-Hooks gehören niemals dazu.

Codebeispiel — Schnellstart

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;
use NextPDF\Event\Document\DocumentCreatedEvent;
use NextPDF\Event\Document\PageAddedEvent;

$provider = new ListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(
    DocumentCreatedEvent::class,
    static function (DocumentCreatedEvent $event): void {
        // react to creation
    },
);

$provider->addListener(
    PageAddedEvent::class,
    static function (PageAddedEvent $event): void {
        // react to a new page: $event->pageIndex
    },
);

$pdf = Document::createStandalone();
$pdf->setEventDispatcher($dispatcher);
$pdf->addPage()->setFont('Helvetica', '', 12)->cell(0, 10, 'Hello')->save('/tmp/out.pdf');

Codebeispiel — Produktion

Dies sind die gängigen prozessinternen Muster:

Audit-Protokollierung. Registrieren Sie für die Basisereignisklasse einen Listener mit niedriger Priorität, sodass er immer zuletzt ausgeführt wird, und protokollieren Sie den Ereignisnamen und den Kontext.
Lizenz-/Limit-Durchsetzung. Registrieren Sie für PageAddedEvent einen Listener mit hoher Priorität. Bei Überschreiten einer Seitenobergrenze stoppen Sie die Weiterleitung und lösen eine typisierte Ausnahme aus.
Nachbearbeitung. Registrieren Sie für DocumentOutputEvent einen Listener und transformieren Sie anschließend die PDF-Bytes, bevor sie zurückgegeben werden.
Sicherheitsüberwachung. Registrieren Sie Listener für SignatureAppliedEvent / EncryptionAppliedEvent und protokollieren Sie level/algorithm sowie Berechtigungsflags in ein Audit-Protokoll.

Prioritätsleitfaden: ≥1000 für security/limit-Prüfungen, 0 für normale Listener und ≤−1000 für audit/telemetry.

Randfälle & Fallstricke

Nicht über einen Remote-Transport verfügbar. Ein Remote-MCP/REST/gRPC-Client kann keinen Listener registrieren; dokumentieren Sie daher keinen Remote-Hook und erwarten Sie ihn auch nicht.
Nur ohne Dispatcher kein Overhead. Sobald ein Dispatcher angehängt ist, fallen die Kosten seiner Listener an; halten Sie Hot-Path-Listener daher schlank.
Weiterleitungssteuerung. Wenn Sie die Weiterleitung stoppen, werden spätere Listener nicht mehr ausgeführt; ordnen Sie Listener daher bewusst nach Priorität.

Performance

Ohne Dispatcher entstehen keine Kosten. Mit Listenern entsprechen die Kosten der Summe der Listener-Arbeit. Für erzeugte Dokumente gilt das Profil structural.

Sicherheitshinweise

Listener können Signier- und Verschlüsselungsereignisse sehen; behandeln Sie daher jedes Audit-Ziel als sensibel. Ein Nachbearbeitungs-Listener, der Ausgabebytes verändert, ist ein Vertrauenspunkt; halten Sie ihn daher minimal und überprüft.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Ereignisklassen werden über die Autoload-Zuordnung aufgelöst.	PSR-4	§3
Der Beispielcode deklariert strikte Typen gemäß dem Standard.	PSR-12	§2.1

Kommerzieller Kontext

Nicht zutreffend — das Ereignissystem gehört zu Core und ist nicht Teil der Remote-Connect-Tool-Oberfläche.

Transportverfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Nein	Es wird kein Event-Listener-Tool bereitgestellt.
REST	Nein	Kein Event-Listener-Endpunkt.
gRPC	Nein	Kein Event-Listener-RPC.
Prozessintern (Bibliothekseinbettung)	Ja	Das oben beschriebene PSR-14-Dispatcher-Muster.

Nutzen Sie bei Remote-Bereitstellungen Telemetrie an der Transportgrenze, statt Engine-Event-Hooks zu erwarten.

HITL-Risikostufe

Nicht zutreffend — hier gibt es kein Connect-Tool, daher ist das Bestätigungs-Gate nicht beteiligt. Prozessinterne Nachbearbeitung, die Dateien schreibt, muss der Host selbst absichern.

JSON-Umschlag des Bestätigungs-Gates

Nicht zutreffend — es wird kein Tool-Aufruf durchgeführt. (Für das Gating von Tool-Aufrufen siehe output-approval.)