内嵌 NextPDF Connect 时观测 PDF 生命周期事件

概览

你可以观测并响应 PDF 生命周期事件——文档创建、页面新增、字体加载、签名应用、输出生成——无需为文档创建子类。**这是一项库内嵌能力，并不是 Connect 工具。**远程 Connect 传输接口（MCP / REST / gRPC）不会公开任何事件监听器工具；只有在以进程内方式承载引擎并接入 dispatcher 时，你才能观测这些事件。本页会明确说明这一边界和进程内模式，避免调用方误以为存在远程挂钩。

安装

composer require nextpdf/server

此模式适用于将引擎内嵌到应用程序并在 PHP 中直接调用的情形，例如自定义服务器宿主端。在远程传输场景下，请改为在传输边界采用遥测与可观测性方案。

概念总览

引擎会通过 PSR-14 风格的 dispatcher 触发事件。你需要创建一个监听器提供者和一个 dispatcher，按事件类注册监听器，再将 dispatcher 附加到文档上。之后，事件会随着文档构建自动触发。未附加 dispatcher 时，事件系统不会引入任何开销，因为每个分派点都只是一次 null 检查。类会通过自动加载的“类→文件”映射解析（PSR-4 §3），所有示例代码也都声明严格类型并遵循编码标准（PSR-12 §2.1）。

API 接口

事件挂钩没有对应的 Connect 工具。工具目录是权威目录，其中没有列出任何事件挂钩。进程内接口由引擎的事件类（DocumentCreatedEvent、PageAddedEvent、FontLoadedEvent、SignatureAppliedEvent、EncryptionAppliedEvent、DocumentOutputEvent）以及监听器提供者和 dispatcher 组成。通过传输可用的工具取决于已安装的层级，而事件挂钩始终不在其中。

代码示例——快速上手

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

代码示例——生产环境

以下是常见的进程内模式：

审计日志。 在基础事件类上以低优先级注册监听器，使其总是最后执行，并记录事件名称与上下文。
授权/限额强制。 以高优先级监听 PageAddedEvent。超过页数上限后，停止传播并抛出带类型的异常。
后处理。 监听 DocumentOutputEvent，然后在 PDF 字节返回前对其进行转换。
安全监控。 监听 SignatureAppliedEvent / EncryptionAppliedEvent，并将 level/algorithm 与权限标志写入审计日志。

优先级指南：security/limit 检查使用 ≥1000，普通监听器使用 0，audit/telemetry 使用 ≤−1000。

边界情况与陷阱

无法通过远程传输使用。 远程 MCP/REST/gRPC 客户端无法注册监听器，因此请勿将其记为可用，也不要期待存在远程挂钩。
唯有在没有 dispatcher 时才是零开销。 附加 dispatcher 会带来其监听器的开销，因此请让热路径上的监听器保持轻量。
传播控制。 停止传播会阻止后续监听器执行，因此请审慎安排优先级。

性能

未附加 dispatcher 时，成本为零。有监听器时，成本就是各监听器工作量的总和。对于所生成的文档，其特性为 structural。

安全注意事项

监听器可以看到签名与加密事件，因此请将任何审计接收端都视为敏感数据处理点。会改动输出字节的后处理监听器是一个信任点，因此请让它保持精简并经过审查。

合规性

陈述	规格	条款	reference_id
事件类会通过自动加载映射解析。	PSR-4	§3
示例代码按照标准声明严格类型。	PSR-12	§2.1

商业背景

不适用——事件系统属于 Core，并不是远程 Connect 工具接口的一部分。

传输可用性

传输	是否可用	备注
MCP (stdio)	否	未公开任何事件监听器工具。
REST	否	没有事件监听器端点。
gRPC	否	没有事件监听器 RPC。
进程内（库内嵌）	是	使用上述 PSR-14 dispatcher 模式。

对于远程部署，请在传输边界通过遥测进行观测，而不要期待引擎的事件挂钩。

HITL 风险层级

不适用——这里没有 Connect 工具，因此不涉及确认关卡。会写入文件的进程内后处理，须由宿主端自行负责防护。

确认关卡 JSON 信封

不适用——并未进行任何工具调用。（关于工具调用的关卡控制，请参阅 output-approval。）