Osservare gli eventi del ciclo di vita PDF nell'embedding di NextPDF Connect

In sintesi

È possibile osservare gli eventi del ciclo di vita del PDF e reagire a essi — documento creato, pagina aggiunta, font caricato, firma applicata, output prodotto — senza estendere il documento tramite sottoclassi. Si tratta di una funzionalità dell’embedding come libreria, non di uno strumento Connect. La superficie di trasporto remoto di Connect (MCP / REST / gRPC) non espone alcuno strumento listener di eventi: gli eventi si osservano quindi solo quando il motore è ospitato in-process e viene collegato un dispatcher. Questa pagina chiarisce esplicitamente questo confine e il pattern in-process, affinché i chiamanti non si aspettino un hook remoto.

Installazione

composer require nextpdf/server

Questo pattern si applica quando l’applicazione incorpora il motore e lo richiama direttamente in PHP, ad esempio in un host server personalizzato. Con un trasporto remoto, preferire invece telemetria e osservabilità al confine del trasporto.

Panoramica concettuale

Il motore emette gli eventi tramite un dispatcher in stile PSR-14. Si creano un listener provider e un dispatcher, si registrano i listener per classe di evento, quindi si collega il dispatcher a un documento. A quel punto, gli eventi vengono emessi automaticamente man mano che il documento viene costruito. Quando non è collegato alcun dispatcher, il sistema di eventi non aggiunge alcun costo, perché ogni punto di dispatch è un controllo di null. Le classi vengono risolte tramite la mappatura classe→file dell’autoload (PSR-4 §3), e tutto il codice di esempio dichiara i tipi stretti e segue lo standard di codifica (PSR-12 §2.1).

Superficie API

Non esiste alcuno strumento Connect per gli hook di evento. Il catalogo degli strumenti è il riferimento da consultare e non ne elenca nessuno. La superficie in-process è costituita dalle classi di evento del motore (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) insieme al listener provider e al dispatcher. Gli strumenti disponibili su un trasporto dipendono dal livello installato, e gli hook di evento non vi rientrano mai.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Seguono i pattern in-process più comuni:

Audit logging. Registrare un listener sulla classe di evento di base con una priorità bassa, in modo che venga eseguito sempre per ultimo, quindi registrare il nome dell’evento e il contesto.
Applicazione di licenza/limiti. Ascoltare PageAddedEvent con una priorità alta. Superato un limite di pagine, interrompere la propagazione e lanciare un’eccezione tipizzata.
Post-elaborazione. Ascoltare DocumentOutputEvent, quindi trasformare i byte del PDF prima che vengano restituiti.
Monitoraggio della sicurezza. Ascoltare SignatureAppliedEvent / EncryptionAppliedEvent e registrare level/algorithm e i flag dei permessi in un log di audit.

Guida alle priorità: ≥1000 per i controlli di security/limit, 0 per i listener normali e ≤−1000 per audit/telemetry.

Casi limite e insidie

Non disponibile su un trasporto remoto. Un client MCP/REST/gRPC remoto non può registrare un listener, perciò non documentare né aspettarsi un hook remoto.
Overhead nullo solo senza un dispatcher. Collegare un dispatcher aggiunge il costo dei suoi listener, perciò mantenere leggeri i listener sui percorsi critici.
Controllo della propagazione. Interrompere la propagazione impedisce l’esecuzione dei listener successivi, perciò ordinarli per priorità in modo intenzionale.

Prestazioni

Senza dispatcher, il costo è nullo. Con i listener, il costo è pari alla somma del lavoro svolto dai listener. Il profilo è structural per i documenti prodotti.

Note di sicurezza

I listener hanno visibilità sugli eventi di firma e di cifratura, perciò trattare qualsiasi sink di audit come sensibile. Un listener di post-elaborazione che modifica i byte di output è un punto di fiducia, perciò mantenerlo minimale e soggetto a revisione.

Conformità

Dichiarazione	Specifica	Clausola	reference_id
Le classi di evento si risolvono tramite la mappatura di autoload.	PSR-4	§3
Il codice di esempio dichiara i tipi stretti secondo lo standard.	PSR-12	§2.1

Contesto commerciale

Non applicabile — il sistema di eventi è Core e non rientra nella superficie degli strumenti Connect remoti.

Disponibilità sul trasporto

Trasporto	Disponibile	Note
MCP (stdio)	No	Non viene esposto alcuno strumento listener di eventi.
REST	No	Nessun endpoint listener di eventi.
gRPC	No	Nessuna RPC listener di eventi.
In-process (embedding come libreria)	Sì	Pattern del dispatcher PSR-14 illustrato sopra.

Per i deployment remoti, osservare il sistema al confine del trasporto tramite telemetria, anziché aspettarsi gli hook di evento del motore.

Livello di rischio HITL

Non applicabile — qui non c’è alcuno strumento Connect, perciò il gate di conferma non è coinvolto. La post-elaborazione in-process che scrive file resta responsabilità dell’host, che deve proteggerla.

Envelope JSON del gate di conferma

Non applicabile — non viene eseguita alcuna chiamata di strumento. (Per il gating delle chiamate di strumento, vedere output-approval.)