NextPDF compat-legacy のブートとディスカバリー

概要

nextpdf/compat-legacy は TCPDF 互換ファサード、つまり NextPDF エンジンに委譲するクラス NextPDF\Compat\Tcpdf\TCPDF を公開します。これは 互換レイヤー であり、ドロップインのクローンではありません。調査対象とした約 120 個の TCPDF 6.x メソッドのうち 94 個を、直接の委譲でカバーします。残りのメソッドには、文書化された動作上の差異があります（/integrations/tcpdf-compat/method-coverage/ を参照）。

オートロード時にグローバルな配線は一切行いません。デフォルトでは、パッケージを require してもグローバルな \TCPDF クラスは作成されません。グローバルエイリアスは明示的にオプトインします。また、移行中に推奨される方法として、ファイル単位でアダプタークラスをインポートします。

TCPDF ファサードの公開方法

ファサードは、PSR-4 でオートロードされる通常のクラスです。

項目	値
ファサードクラス	`NextPDF\Compat\Tcpdf\TCPDF`
PSR-4 プレフィックス	`NextPDF\Compat\Tcpdf\` は `src/Compat/Tcpdf/` に対応
共有コントラクト	`NextPDF\Compat\Contracts\CompatAdapterInterface`
エスケープハッチ	`TCPDF::getDocument()` はラップされた `NextPDF\Core\Document` を返す

このクラスは意図的に final ではありません。レガシーな TCPDF ユーザーは、Header() と Footer() をオーバーライドするために TCPDF をサブクラス化することがよくあるため、アダプターはその拡張ポイントを保持します。内部的には、このクラスはファサードです。単一責任ごとの関心事を表す 25 個のトレイトを組み合わせ、すべての PDF 操作を、ビルド時に構築される Document インスタンスに委譲します。

ブートシーケンス

Diagram

構築が唯一の「ブート」ステップです。パッケージ自体には、サービスコンテナの登録もフレームワークのブートストラップもありません。フレームワーク統合は、自分で追加する薄いレイヤーです（/integrations/tcpdf-compat/integration/. を参照）。

LegacyDefaults::register() は冪等です。定数がまだ定義されていない場合にのみ、その定数を定義します。アプリケーション側で定義した定数は、最初の構築より前に定義しておけば、常に優先されます（/integrations/tcpdf-compat/configuration/ § Configuration resolution order を参照）。

オプトインのグローバルクラスエイリアス

コードベースがグローバル名前空間の new \TCPDF(...) を呼び出しており、それらの呼び出し箇所をまだ変更できない場合は、アプリケーションのブート時に一度だけグローバルエイリアスを登録します。

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() は \TCPDF、\TCPDF_STATIC、\TCPDF_FONTS、\TCPDF_COLORS、および \TCPDF_IMAGES を登録します。tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php によって検証されている動作は、次のとおりです。

これは冪等です。2 回呼び出しても例外をスローせず、登録は 1 回だけ行われます。
LegacyBootstrap::isRegistered() は、それがすでに実行されたかどうかを報告します。
登録後の new \TCPDF() は、アダプターのインスタンスになります。

実際の TCPDF インストールとの競合回避

このページで最も重要なルールは、これだけです。

enableAliases() は、その名前のクラスがまだ存在しない場合にのみ エイリアスを登録します（class_exists($alias, autoload: false)）。したがって:

tecnickcom/tcpdf がインストールされており、その \TCPDF が先に読み込まれた場合、エイリアスは 暗黙のうちにスキップされ、コードはアダプターではなくレガシーな TCPDF を使い続けます。
グローバルエイリアスを有効にした状態で、両方のライブラリを同一プロセス内で実行することはサポートされておらず、曖昧な動作を引き起こします。

移行中は、ファイルごとの明示的なインポート（use NextPDF\Compat\Tcpdf\TCPDF;）を優先します。これらは grep で検索でき、曖昧さがありません。strict モードの監査に合格したら、tecnickcom/tcpdf を削除します（/integrations/tcpdf-compat/migration/ Stage 5 を参照）。\TCPDF が誤ったクラスに解決される場合は、/integrations/tcpdf-compat/troubleshooting/ に診断方法があります。

コンテナバインディング

このパッケージは、フレームワークのコンテナバインディングを一切同梱していません。ファサードをコンテナにバインドする場合は、ドキュメントごとに新しい NextPDF\Compat\Tcpdf\TCPDF を返すファクトリをバインドします。ドキュメントの状態はインスタンス単位であり、無関係なドキュメント間で共有してはなりません（/integrations/tcpdf-compat/production-usage/ § Concurrency を参照）。典型的なバインディングは /integrations/tcpdf-compat/integration/. に示されています。

設定の解決順序

構築時に、アダプターは次の順序で設定を解決します。まずコンストラクター引数、次に既存のアプリケーション定義のレガシー定数、最後に、まだ定義されていない定数については LegacyDefaults の TCPDF 6.2.13 デフォルト値を使います。詳細とモダンな AdaptationConfig オブジェクトについては、/integrations/tcpdf-compat/configuration/. を参照してください。

診断

ファサードが配線され、エンジンへのリンクが解決されることを確認するには、アダプターを構築して 1 ページの PDF を生成し、%PDF プレフィックスを確認します。これは、パッケージの出力テストが検証している内容と同じ確認面です。実行可能なチェックは /integrations/tcpdf-compat/install/ § Verify the installation にあります。

エイリアスを有効にする前に実際の TCPDF との競合を検出するには、enableAliases() を呼び出す予定の時点で、グローバルな \TCPDF がすでに存在するかどうかを確認します。存在する場合はエイリアスがスキップされるため、アダプターに依存する前に競合を解消してください（明示的なインポートを使うか、実際の TCPDF を削除します）。

TCPDF API カバレッジ

信頼できるテスト検証済みのカバレッジマトリックスは、リポジトリ内のファイル docs/TCPDF_COVERAGE.md です。サイレント無視および未実装のメソッド一覧を含む読者向けの概要は、/integrations/tcpdf-compat/method-coverage/. です。このパッケージは「ドロップイン代替」や「100% TCPDF 互換」を謳うものではありません。既知でテスト済みの互換性の範囲と、文書化された動作上の差異を持つ、TCPDF 互換の代替手段です。