拡張機能の作成：公開 SPI の概要

概要

NextPDF は、意図的に絞り込んだ小規模な公開コントラクト群を公開しており、これらはすべて NextPDF\Contracts および NextPDF\Event 名前空間に配置されています。これらのコントラクトを実装することで、エンジンをフォークせずに、フォントの追加、テキストのインターセプト、ドキュメントライフサイクルの監視、独自の署名バックエンドの提供ができます。

インストール

composer require nextpdf/core:^3

概念の概要

NextPDF は、公開サービスプロバイダーインターフェイス（SPI） を内部コードから分離しています。SPI は、実装または監視してよい型の集合です。それ以外はすべてプライベートであり、予告なく変更される場合があります。

公開 SPI には、3 つの形態があります。

レジストリコントラクト。 ドキュメントを作成する前に内容を設定する、プロセス存続期間中のサービスです。FontRegistryInterface と ImageRegistryInterface が主な例です。アセットを登録すると、エンジンがそれらを読み取ります。
ストラテジーコントラクト。 レンダリング中にエンジンから呼び出される、単一の役割に絞ったフックです。TextPreprocessorInterface はレイアウト時のテキストのインターセプトを処理し、HtmlSecurityPolicyInterface は HTML 機能を制御します。動作を提供すると、エンジンがそれを駆動します。
署名コントラクト。 暗号処理のバックエンドです。SignerInterface、HsmSignerInterface、DeferredSignerInterface を使用すると、鍵の保管と署名の生成を提供できます。エンジンが CMS 構造を構築し、ユーザーコードが鍵を保持します。

独立した PSR-14 互換イベントシステムが NextPDF\Event 内で監視を処理します。ライフサイクルイベントを使用すると、ドキュメント作成、新規ページ、フォント読み込み、署名、書き出しに反応できます。これらはエンジンの動作を変更しません。

各コントラクトには、そのソース PHPDoc 内に @stability タグがあります。値は stable、experimental、または deprecated です。このタグと、コントラクトごとの後方互換性の約束により、想定すべき変更の程度がわかります。完全なポリシーについては、SPI 安定性ルールを参照してください。

拡張可能な対象

機能	公開コントラクト	安定性
フォントの登録と参照	`NextPDF\Contracts\FontRegistryInterface`	stable (1.7.0 から)
画像のキャッシュとデコード	`NextPDF\Contracts\ImageRegistryInterface`	stable (2.0.0 から)
レイアウト時のテキストのインターセプト	`NextPDF\Contracts\TextPreprocessorInterface`	stable (1.9.0 から)
HTML 機能の制御	`NextPDF\Contracts\HtmlSecurityPolicyInterface`	stable (3.1.0 から)
ドキュメントファクトリーの配線	`NextPDF\Contracts\DocumentFactoryInterface`	stable (1.7.0 から)
同期署名	`NextPDF\Contracts\SignerInterface`	stable (1.0.0 から)
ハードウェアベースの署名	`NextPDF\Contracts\HsmSignerInterface`	stable (1.0.0 から)
遅延署名およびバッチ署名	`NextPDF\Contracts\DeferredSignerInterface`	experimental (3.0.0 から)
RFC 3161 タイムスタンプ	`NextPDF\Contracts\TimestampProviderInterface`	experimental (3.0.0 から)
ライフサイクルの監視	`NextPDF\Event\*` (PSR-14 と互換)	ディスパッチャーは stable；ペイロードは experimental

公開されていない対象

以下は内部的なものです。これらをインポート、サブクラス化、依存の対象にしないでください。

NextPDF\Contracts および NextPDF\Event 名前空間の外側にあるクラス。ただし、その PHPDoc に @stability タグが付いているものを除きます。
HTML パーサー、ライター、レイアウトパイプライン、フォントサブセッターなど、エンジンの具体的な実装コード。
NextPDF Pro および NextPDF Enterprise パッケージ。これらの内部クラスは、オープンソースの公開対象には含まれません。有料エディションが SPI 実装を提供する場合も、利用するのは公開コントラクトであり、その内部型ではありません。

API 公開対象

正式な一覧は、生成されたコントラクトマップです。これはリリースごとにソースから再構築されます。各インターフェイスファイル内の @stability PHPDoc タグを、唯一の信頼できる情報源として扱ってください。上記の表は、理解を助けるための補助情報です。

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

フォントを登録し、それが読み込まれるタイミングを監視します。どちらの手順でも、公開型のみを使用します。

<?php

declare(strict_types=1);

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Event\Content\FontLoadedEvent;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;

/** @var FontRegistryInterface $fonts */
$fonts->register('/srv/fonts/Inter-Regular.ttf', 'Inter');

$listeners = new ListenerProvider();
$listeners->addListener(
    FontLoadedEvent::class,
    static function (FontLoadedEvent $event): void {
        \error_log("Font loaded: {$event->family} {$event->style}");
    },
);

$dispatcher = new EventDispatcher($listeners);

コードサンプル — 本番環境

長時間実行されるワーカーでは、起動時にレジストリを一度だけ構築してロックし、ドキュメントファクトリー経由で共有ディスパッチャーを注入します。

<?php

declare(strict_types=1);

use NextPDF\Contracts\DocumentFactoryInterface;
use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;
use Psr\Log\LoggerInterface;

final class DocumentBootstrap
{
    public function __construct(
        private readonly FontRegistryInterface $fonts,
        private readonly DocumentFactoryInterface $factory,
        private readonly LoggerInterface $logger,
    ) {}

    public function warmup(): EventDispatcher
    {
        $this->fonts->warmup([
            '/srv/fonts/Inter-Regular.ttf',
            '/srv/fonts/Inter-Bold.ttf',
        ]);
        $this->fonts->lock();

        $listeners = new ListenerProvider();
        $listeners->addListener(
            \NextPDF\Event\Security\SignatureAppliedEvent::class,
            fn (object $event): mixed => $this->logger->info('Signature applied'),
        );

        return new EventDispatcher($listeners);
    }
}

エッジケースと注意点

レジストリのロック。 FontRegistryInterface::lock() の後は、変更メソッドが LogicException をスローします。ロックは、ウォームアップ完了後にのみ行ってください。
安定性の不一致。 experimental コントラクトは、マイナーリリースで変更される可能性があります。本番環境でコントラクトに依存する前には、明示された安定性を確認してください。
名前空間の規律。 NextPDF\Contracts または NextPDF\Event の外側にあり、@stability タグを持たない型は内部的なものです。これは、技術的に public であっても同じです。

パフォーマンス

SPI は未使用時のコストがゼロです。あるイベントクラスにリスナーがバインドされていない場合、イベントディスパッチャーは 1 回の hasListeners() チェックの後、ただちに戻ります。レジストリは純粋な PHP データを保持し、初回リクエストのレイテンシを分散させるための起動時ウォームアップをサポートします。

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

署名コントラクトは、セキュリティ上重要です。HsmSignerInterface では、秘密鍵がハードウェア境界の外に決して出ないことが要求されます。実装側でこの要件を順守する必要があります。サードパーティの署名バックエンドコントラクトとその脅威モデルについては、KMS プロバイダーコントラクトを参照してください。

準拠性

この概要ページでは、規範的な主張は行いません。コントラクトごとの準拠性（PAdES、鍵管理）は、該当する SPI ページに記載されています。

商用に関する背景情報

NextPDF Pro および NextPDF Enterprise は、鍵管理システムベースの署名を含む、いくつかの署名コントラクトおよび検証コントラクトについて本番環境向け実装を提供します。実装は各エディションが提供しますが、依存先は公開コントラクトであるため、コードはエディションをまたいで移植可能な状態を維持できます。