NextPDF Connect を組み込む際の PDF ライフサイクルイベントの監視

概要

ドキュメントをサブクラス化せずに、PDF のライフサイクルイベント（ドキュメント作成、ページ追加、フォント読み込み、署名適用、出力生成）を監視し、対応できます。これはライブラリ組み込みの機能であり、Connect ツールではありません。 リモート Connect のトランスポート面（MCP / REST / gRPC）はイベントリスナーツールを公開していないため、エンジンをインプロセスでホストしてディスパッチャーを接続した場合にのみイベントを監視できます。このページでは、その境界とインプロセスのパターンを明確に示し、呼び出し側がリモートフックを期待しないようにします。

インストール

composer require nextpdf/server

このパターンは、アプリケーションがエンジンを組み込み、カスタムサーバーホストなどで PHP から直接呼び出す場合に適用されます。リモートトランスポートを経由する場合は、代わりにトランスポート境界でテレメトリーと可観測性を確保することを推奨します。

概念の概要

エンジンは PSR-14 スタイルのディスパッチャーを通じてイベントを発火します。リスナープロバイダーとディスパッチャーを作成し、イベントクラスごとにリスナーを登録してから、ディスパッチャーをドキュメントに接続します。以後は、ドキュメントの構築に伴ってイベントが自動的に発火します。ディスパッチャーが接続されていない場合、各ディスパッチポイントで行うのは null チェックだけであるため、イベントシステムのコストはゼロになります。クラスはオートロードのクラス→ファイルマッピング（PSR-4 §3）を通じて解決され、すべてのサンプルコードは厳格な型を宣言し、コーディング標準（PSR-12 §2.1）に従います。

API 面

イベントフック用の Connect ツールはありません。ツールカタログが正式なカタログであり、イベントフックは掲載されていません。インプロセス側では、エンジンのイベントクラス（DocumentCreatedEvent、PageAddedEvent、FontLoadedEvent、SignatureAppliedEvent、EncryptionAppliedEvent、DocumentOutputEvent）と、リスナープロバイダーおよびディスパッチャーを使用します。トランスポート経由で利用できるツールはインストールされているティアに依存しますが、イベントフックがそこに含まれることは決してありません。

コードサンプル — クイックスタート

<?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 クライアントはリスナーを登録できないため、リモートフックを文書化したり、期待したりしないでください。
ゼロオーバーヘッドはディスパッチャーがない場合のみ。 ディスパッチャーを接続するとリスナーのコストが加わるため、ホットパスのリスナーは軽量に保ってください。
伝播の制御。 伝播を停止すると後続のリスナーが実行されなくなるため、優先度の順序を意図的に決めてください。

パフォーマンス

ディスパッチャーがない場合、コストはゼロです。リスナーがある場合、コストはリスナーの作業の合計です。生成されるドキュメントのプロファイルは structural です。

セキュリティに関する注意

リスナーは署名イベントと暗号化イベントを参照できるため、すべての監査シンクを機密として扱ってください。出力バイト列を変更する後処理リスナーは信頼ポイントであるため、最小限に保ち、レビューしてください。

準拠

ステートメント	仕様	条項	reference_id
イベントクラスはオートロードマッピングで解決される。	PSR-4	§3
サンプルコードは標準に従い、厳格な型を宣言する。	PSR-12	§2.1

商用コンテキスト

該当なし — イベントシステムは Core に含まれ、リモートの Connect ツール面の一部ではありません。

トランスポートの利用可否

トランスポート	利用可否	備考
MCP (stdio)	不可	イベントリスナーツールは公開されない。
REST	不可	イベントリスナーエンドポイントなし。
gRPC	不可	イベントリスナー RPC なし。
インプロセス（ライブラリ組み込み）	可	上記の PSR-14 ディスパッチャーパターン。

リモートデプロイメントでは、エンジンのイベントフックを期待するのではなく、トランスポート境界でテレメトリーを用いて監視してください。

HITL リスクティア

該当なし — ここには Connect ツールがないため、確認ゲートは関与しません。ファイルを書き込むインプロセスの後処理は、ホスト自身が保護する責任を負います。

確認ゲートの JSON エンベロープ

該当なし — ツール呼び出しは行われません。（ツール呼び出しのゲーティングについては output-approval を参照してください。）