PDF-levenscyclusgebeurtenissen observeren wanneer je NextPDF Connect inbedt

In een oogopslag

Je kunt PDF-levenscyclusgebeurtenissen observeren en erop reageren — bijvoorbeeld wanneer een document is aangemaakt, een pagina is toegevoegd, een lettertype is geladen, een handtekening is toegepast of uitvoer is geproduceerd — zonder het document te subclassen. Dit is een functie voor bibliotheekinbedding, geen Connect-tool. Het externe Connect-transportvlak (Model Context Protocol (MCP) / REST / gRPC) biedt geen event-listenertool. Je observeert gebeurtenissen alleen wanneer je de engine in-process host en een dispatcher koppelt. Deze pagina bakent die grens duidelijk af en laat het in-process-patroon zien, zodat aanroepers geen externe hook verwachten.

Installeren

composer require nextpdf/server

Gebruik dit patroon wanneer je applicatie de engine inbedt en deze rechtstreeks in PHP aanroept, bijvoorbeeld vanuit een aangepaste serverhost. Bij extern transport observeer je het systeem in plaats daarvan via telemetrie op de transportgrens.

Conceptueel overzicht

De engine vuurt gebeurtenissen af via een dispatcher in PSR-14-stijl. Je maakt een listener provider en dispatcher, registreert listeners per gebeurtenisklasse en koppelt de dispatcher daarna aan een document. Vanaf dat moment worden gebeurtenissen automatisch afgevuurd terwijl het document wordt opgebouwd. Wanneer er geen dispatcher is gekoppeld, voegt het gebeurtenissysteem geen kosten toe, omdat elk dispatch-punt een null-controle is. Klassen worden opgelost via de autoload-mapping van klasse naar bestand (PSR-4 §3), en alle voorbeeldcode declareert strict types en volgt de codeerstandaard (PSR-12 §2.1).

API-vlak

Er is geen Connect-tool voor event hooks. De toolcatalogus is de gezaghebbende catalogus; daarin wordt er geen vermeld. Het in-process-vlak bestaat uit de gebeurtenisklassen van de engine (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) samen met de listener provider en dispatcher. De tools die via een transport beschikbaar zijn, hangen af van het geïnstalleerde niveau, en event hooks behoren daar nooit toe.

Codevoorbeeld — Snel starten

<?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');

Codevoorbeeld — Productie

Gebruik deze veelvoorkomende in-process-patronen:

Auditlogging. Registreer een listener voor de basisgebeurtenisklasse met een lage prioriteit, zodat deze altijd als laatste wordt uitgevoerd, en leg de gebeurtenisnaam en context vast.
Licentie-/limiethandhaving. Luister naar PageAddedEvent met een hoge prioriteit. Stop de propagatie wanneer een paginalimiet wordt overschreden en werp een getypeerde exception op.
Naverwerking. Luister naar DocumentOutputEvent en transformeer vervolgens de PDF-bytes voordat ze worden geretourneerd.
Beveiligingsmonitoring. Luister naar SignatureAppliedEvent / EncryptionAppliedEvent en leg level/algorithm en permissievlaggen vast in een auditlog.

Prioriteitsrichtlijn: ≥1000 voor security/limit-controles, 0 voor normale listeners en ≤−1000 voor audit/telemetry.

Randgevallen en valkuilen

Niet beschikbaar via extern transport. Een externe MCP/REST/gRPC-client kan geen listener registreren; documenteer dus geen externe hook en verwacht die ook niet.
Nul overhead alleen zonder dispatcher. Het koppelen van een dispatcher voegt de kosten van de listeners toe, dus houd listeners op het hot path goedkoop.
Propagatiebeheer. Het stoppen van de propagatie voorkomt dat latere listeners worden uitgevoerd; rangschik listeners dus bewust op prioriteit.

Prestaties

Zonder dispatcher zijn de kosten nul. Met listeners komen de kosten neer op de som van hun werk. Het profiel is structural voor geproduceerde documenten.

Beveiligingsopmerkingen

Listeners kunnen ondertekenings- en versleutelingsgebeurtenissen zien; behandel elke audit-sink daarom als gevoelig. Een naverwerkingslistener die uitvoerbytes muteert, vormt een vertrouwenspunt; houd hem daarom minimaal en review hem zorgvuldig.

Conformiteit

Bewering	Spec	Clausule	reference_id
Gebeurtenisklassen worden via de autoload-mapping opgelost.	PSR-4	§3
Voorbeeldcode declareert strict types conform de standaard.	PSR-12	§2.1

Commerciële context

Niet van toepassing — het gebeurtenissysteem is Core en maakt geen deel uit van het externe Connect-toolvlak.

Transportbeschikbaarheid

Transport	Beschikbaar	Opmerkingen
MCP (stdio)	Nee	Er wordt geen event-listenertool aangeboden.
REST	Nee	Geen event-listener-endpoint.
gRPC	Nee	Geen event-listener-RPC.
In-process (bibliotheekinbedding)	Ja	Het bovenstaande PSR-14-dispatcherpatroon.

Bij externe implementaties observeer je de transportgrens met telemetrie in plaats van engine-event hooks te verwachten.

HITL-risiconiveau

Niet van toepassing — er is hier geen Connect-tool, dus de bevestigingsgate speelt geen rol. De host moet elke in-process-naverwerking die bestanden schrijft, beveiligen.

JSON-envelop van de bevestigingsgate

Niet van toepassing — er wordt geen tool-aanroep gedaan. (Zie voor gating van tool-aanroepen output-approval.)