Observar los eventos del ciclo de vida del PDF al integrar NextPDF Connect

En resumen

Es posible observar los eventos del ciclo de vida del PDF y reaccionar a ellos —documento creado, página añadida, fuente cargada, firma aplicada, salida producida— sin crear subclases del documento. Esta es una capacidad de integración como biblioteca, no una herramienta de Connect. La superficie de transporte remoto de Connect (MCP / REST / gRPC) no expone ninguna herramienta de escucha de eventos, por lo que los eventos solo se observan cuando el motor se aloja en proceso y se conecta un despachador. Esta página deja claro ese límite y el patrón en proceso, para evitar que los consumidores esperen un enganche remoto.

Instalación

composer require nextpdf/server

Este patrón se aplica cuando la aplicación integra el motor y lo invoca directamente en PHP, como en un host de servidor personalizado. En un transporte remoto, conviene preferir la telemetría y la observabilidad en el límite del transporte.

Panorama conceptual

El motor emite eventos a través de un despachador de estilo PSR-14. El patrón consiste en crear un proveedor de escuchadores y un despachador, registrar los escuchadores por clase de evento y, después, adjuntar el despachador a un documento. A partir de ahí, los eventos se emiten automáticamente conforme se construye el documento. Cuando no hay ningún despachador adjunto, el sistema de eventos no añade ningún coste, porque cada punto de despacho es una comprobación de null. Las clases se resuelven a través de la asignación de clase→archivo de la carga automática (PSR-4 §3), y todo el código de ejemplo declara tipos estrictos y sigue el estándar de codificación (PSR-12 §2.1).

Superficie de la API

No hay ninguna herramienta de Connect para los enganches de eventos. El catálogo de herramientas es la referencia canónica y no incluye ninguna. La superficie en proceso está formada por las clases de evento del motor (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) junto con el proveedor de escuchadores y el despachador. Las herramientas disponibles mediante un transporte dependen del nivel instalado, y los enganches de eventos nunca forman parte de ellas.

Código de ejemplo — Inicio rápido

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

Código de ejemplo — Producción

Estos son los patrones en proceso más comunes:

Registro de auditoría. Registrar un escuchador en la clase de evento base con una prioridad baja para que siempre se ejecute al final, y registrar el nombre del evento y su contexto.
Aplicación de licencias/límites. Escuchar en PageAddedEvent con una prioridad alta. Una vez superado un tope de páginas, detener la propagación y lanzar una excepción tipada.
Posprocesamiento. Escuchar en DocumentOutputEvent y, después, transformar los bytes del PDF antes de que se devuelvan.
Supervisión de seguridad. Escuchar en SignatureAppliedEvent / EncryptionAppliedEvent y registrar el level/algorithm y los indicadores de permisos en un registro de auditoría.

Guía de prioridades: ≥1000 para comprobaciones de security/limit, 0 para escuchadores normales y ≤−1000 para audit/telemetry.

Casos límite y trampas

No disponible a través de un transporte remoto. Un cliente remoto MCP/REST/gRPC no puede registrar un escuchador; por tanto, no se debe documentar ni esperar un enganche remoto.
Sin sobrecarga solo cuando no hay un despachador. Adjuntar un despachador añade el coste de sus escuchadores, así que conviene mantener ligeros los escuchadores de la ruta crítica.
Control de la propagación. Detener la propagación impide que se ejecuten los escuchadores posteriores, así que conviene ordenar por prioridad de forma deliberada.

Rendimiento

Sin un despachador, el coste es cero. Con escuchadores, el coste equivale a la suma del trabajo de los escuchadores. El perfil de los documentos producidos es structural.

Notas de seguridad

Los escuchadores pueden ver los eventos de firma y cifrado; por tanto, cualquier destino de auditoría debe tratarse como sensible. Un escuchador de posprocesamiento que muta los bytes de salida es un punto de confianza; por tanto, debe mantenerse mínimo y revisado.

Conformidad

Afirmación	Especificación	Cláusula	reference_id
Las clases de evento se resuelven a través de la asignación de la carga automática.	PSR-4	§3
El código de ejemplo declara tipos estrictos según el estándar.	PSR-12	§2.1

Contexto comercial

No aplicable: el sistema de eventos forma parte de Core y no de la superficie de herramientas remotas de Connect.

Disponibilidad por transporte

Transporte	Disponible	Notas
MCP (stdio)	No	No se expone ninguna herramienta de escucha de eventos.
REST	No	No hay ningún punto de conexión de escucha de eventos.
gRPC	No	No hay ningún RPC de escucha de eventos.
En proceso (integración como biblioteca)	Sí	El patrón de despachador PSR-14 descrito arriba.

En despliegues remotos, observar en el límite del transporte con telemetría, en lugar de esperar enganches de eventos del motor.

Nivel de riesgo HITL

No aplicable: aquí no hay ninguna herramienta de Connect, por lo que la compuerta de confirmación no interviene. Corresponde al propio host proteger el posprocesamiento en proceso que escribe archivos.

Envoltorio JSON de la compuerta de confirmación

No aplicable: no se realiza ninguna llamada a herramientas. (Para controlar las llamadas a herramientas, consultar output-approval.)