Observe eventos do ciclo de vida de PDFs ao integrar o NextPDF Connect

Visão geral

Você pode observar eventos do ciclo de vida do PDF e reagir a eles — documento criado, página adicionada, fonte carregada, assinatura aplicada, saída produzida — sem criar subclasses do documento. Este é um recurso de integração de biblioteca, não uma ferramenta do Connect. A superfície de transporte remoto do Connect (Model Context Protocol (MCP) / REST / gRPC) não expõe nenhuma ferramenta para escutar eventos. Você só consegue observar eventos quando hospeda o motor em processo e conecta um dispatcher. Esta página delimita esse escopo e mostra com clareza o padrão em processo, para que os chamadores não esperem um hook remoto.

Instalação

composer require nextpdf/server

Use esse padrão quando a aplicação integra o motor e o chama diretamente em PHP, como a partir de um host de servidor personalizado. Em um transporte remoto, observe o sistema no limite do transporte com telemetria.

Visão conceitual

O motor dispara eventos por meio de um dispatcher no estilo PSR-14. Você cria um listener provider e um dispatcher, registra listeners por classe de evento e, em seguida, anexa o dispatcher a um documento. A partir daí, os eventos são disparados automaticamente conforme o documento é construído. Quando nenhum dispatcher está anexado, o sistema de eventos não acrescenta custo algum, porque cada ponto de despacho é uma verificação de null. As classes são resolvidas pelo mapeamento de autoload classe→arquivo (PSR-4 §3), e todo o código de exemplo declara strict types e segue o padrão de codificação (PSR-12 §2.1).

Superfície da API

Não existe nenhuma ferramenta do Connect para hooks de eventos. O catálogo de ferramentas é o catálogo oficial, e ele não lista nenhuma ferramenta desse tipo. A superfície em processo é composta pelas classes de evento do motor (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) junto com o listener provider e o dispatcher. As ferramentas disponíveis em um transporte dependem do tier instalado, e os hooks de eventos nunca estão entre elas.

Exemplo de código — Início 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');

Exemplo de código — Produção

Use estes padrões comuns em processo:

Registro de auditoria. Registre um listener na classe de evento base com baixa prioridade para que ele sempre seja executado por último, e registre o nome e o contexto do evento.
Imposição de licença/limite. Escute o PageAddedEvent com prioridade alta. Quando o documento ultrapassar um limite de páginas, interrompa a propagação e lance uma exceção tipada.
Pós-processamento. Escute o DocumentOutputEvent e, em seguida, transforme os bytes do PDF antes que sejam retornados.
Monitoramento de segurança. Escute o SignatureAppliedEvent / EncryptionAppliedEvent e registre o level/algorithm e os flags de permissão em um log de auditoria.

Guia de prioridade: ≥1000 para verificações de security/limit, 0 para listeners normais e ≤−1000 para audit/telemetry.

Casos extremos e armadilhas

Não disponível em um transporte remoto. Um cliente remoto MCP/REST/gRPC não pode registrar um listener; portanto, não documente nem espere um hook remoto.
Sobrecarga zero apenas sem um dispatcher. Anexar um dispatcher adiciona o custo dos seus listeners, então mantenha leves os listeners do caminho crítico.
Controle de propagação. Interromper a propagação impede que listeners posteriores sejam executados, então ordene-os por prioridade de forma deliberada.

Desempenho

Sem um dispatcher, o custo é zero. Com listeners, o custo corresponde à soma do trabalho deles. O perfil é structural para os documentos produzidos.

Notas de segurança

Os listeners podem ver eventos de assinatura e criptografia, então trate todo destino de auditoria como sensível. Um listener de pós-processamento que altera os bytes de saída é um ponto de confiança, então mantenha-o mínimo e sob revisão.

Conformidade

Declaração	Especificação	Cláusula	reference_id
As classes de evento são resolvidas pelo mapeamento de autoload.	PSR-4	§3
O código de exemplo declara strict types conforme o padrão.	PSR-12	§2.1

Contexto comercial

Não aplicável — o sistema de eventos é Core e não faz parte da superfície de ferramentas remotas do Connect.

Disponibilidade por transporte

Transporte	Disponível	Notas
MCP (stdio)	Não	Nenhuma ferramenta de escuta de eventos é exposta.
REST	Não	Nenhum endpoint de escuta de eventos.
gRPC	Não	Nenhum RPC de escuta de eventos.
Em processo (integração da biblioteca)	Sim	O padrão de dispatcher PSR-14 descrito acima.

Para implantações remotas, observe o sistema no limite do transporte usando telemetria, em vez de esperar hooks de eventos do motor.

Nível de risco HITL

Não aplicável — não há ferramenta do Connect aqui, então o portão de confirmação não está envolvido. O host deve proteger qualquer pós-processamento em processo que grave arquivos.

Envelope JSON do portão de confirmação

Não aplicável — nenhuma chamada de ferramenta é feita. (Para o controle das chamadas de ferramentas, consulte output-approval.)