內嵌 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。）