Observer les événements du cycle de vie d'un PDF dans une intégration NextPDF Connect

En bref

Tu peux observer les événements du cycle de vie d’un PDF — document créé, page ajoutée, police chargée, signature appliquée, sortie produite — et y réagir, sans sous-classer le document. C’est une capacité d’intégration en tant que bibliothèque, pas un outil Connect. La surface de transport distant de Connect (MCP / REST / gRPC) n’expose aucun outil d’écoute d’événements ; tu observes donc les événements uniquement lorsque tu héberges le moteur in-process et que tu branches un dispatcher. Cette page explicite cette limite et le motif in-process, afin que les appelants ne s’attendent pas à disposer d’un hook distant.

Installation

composer require nextpdf/server

Ce motif s’applique quand ton application intègre le moteur et l’appelle directement en PHP, par exemple depuis un hôte serveur personnalisé. Avec un transport distant, privilégie plutôt la télémétrie et l’observabilité à la frontière du transport.

Vue d’ensemble conceptuelle

Le moteur déclenche les événements via un dispatcher de style PSR-14. Tu crées un fournisseur d’écouteurs et un dispatcher, tu enregistres les écouteurs par classe d’événement, puis tu associes le dispatcher à un document. À partir de là, les événements se déclenchent automatiquement à mesure que le document est construit. Lorsqu’aucun dispatcher n’est attaché, le système d’événements n’entraîne aucun coût, car chaque point de dispatch est une vérification null. Les classes sont résolues via le mappage d’autoload classe→fichier (PSR-4 §3), et tout le code d’exemple déclare des types stricts et suit la norme de codage (PSR-12 §2.1).

Surface de l’API

Il n’existe aucun outil Connect pour les hooks d’événements. Le catalogue d’outils fait foi, et il n’en répertorie aucun. La surface in-process se compose des classes d’événements du moteur (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) ainsi que du fournisseur d’écouteurs et du dispatcher. Les outils disponibles sur un transport dépendent du palier installé, et les hooks d’événements n’en font jamais partie.

Exemple de code — Démarrage rapide

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

Exemple de code — Production

Voici les motifs in-process courants :

Journalisation d’audit. Enregistre un écouteur sur la classe d’événement de base avec une priorité faible pour qu’il s’exécute toujours en dernier, puis consigne le nom de l’événement et son contexte.
Application des licences/limites. Écoute PageAddedEvent avec une priorité élevée. Au-delà d’un plafond de pages, arrête la propagation et lève une exception typée.
Post-traitement. Écoute DocumentOutputEvent, puis transforme les octets du PDF avant qu’ils ne soient renvoyés.
Surveillance de la sécurité. Écoute SignatureAppliedEvent / EncryptionAppliedEvent, puis consigne le level/algorithm et les drapeaux de permissions dans un journal d’audit.

Guide des priorités : ≥1000 pour les vérifications security/limit, 0 pour les écouteurs normaux, et ≤−1000 pour audit/telemetry.

Cas limites et pièges

Indisponible sur un transport distant. Un client MCP/REST/gRPC distant ne peut pas enregistrer d’écouteur ; ne documente donc pas un hook distant et ne t’attends pas à en disposer.
Coût nul uniquement sans dispatcher. Attacher un dispatcher ajoute le coût de ses écouteurs ; veille donc à garder légers les écouteurs du chemin critique.
Contrôle de la propagation. Arrêter la propagation empêche les écouteurs suivants de s’exécuter ; ordonne-les donc par priorité de manière délibérée.

Performance

Sans dispatcher, le coût est nul. Avec des écouteurs, le coût est la somme du travail des écouteurs. Le profil est structural pour les documents produits.

Notes de sécurité

Les écouteurs peuvent voir les événements de signature et de chiffrement ; traite donc toute destination d’audit comme sensible. Un écouteur de post-traitement qui modifie les octets de sortie est un point de confiance ; garde-le minimal et soumis à revue.

Conformité

Énoncé	Spéc.	Clause	reference_id
Les classes d’événements se résolvent via le mappage d’autoload.	PSR-4	§3
Le code d’exemple déclare des types stricts conformément à la norme.	PSR-12	§2.1

Contexte commercial

Sans objet — le système d’événements relève de Core, et il ne fait pas partie de la surface distante des outils Connect.

Disponibilité par transport

Transport	Disponible	Notes
MCP (stdio)	Non	Aucun outil d’écoute d’événements n’est exposé.
REST	Non	Aucun point d’accès pour l’écoute d’événements.
gRPC	Non	Aucun RPC pour l’écoute d’événements.
In-process (intégration en bibliothèque)	Oui	Le motif de dispatcher PSR-14 décrit ci-dessus.

Pour les déploiements distants, observe à la frontière du transport au moyen de télémétrie, plutôt que de t’attendre à des hooks d’événements du moteur.

Niveau de risque HITL

Sans objet — il n’y a pas d’outil Connect ici, donc le portail de confirmation n’intervient pas. Il revient à l’hôte de protéger le post-traitement in-process qui écrit des fichiers.

Enveloppe JSON du portail de confirmation

Sans objet — aucun appel d’outil n’est effectué. (Pour le contrôle des appels d’outils, voir output-approval.)