NextPDF compat-legacy の概要

概要

nextpdf/compat-legacy は TCPDF 互換の代替手段 であり、NextPDF の PDF 2.0 エンジン上で TCPDF 6.x の公開 API を提供する互換レイヤーです。目的はただ一つ、すでに TCPDF 6.x に依存しているコードベースを、書き換えなしで NextPDF エンジン上で動作させ、移行を一度に行うのではなくファイル単位で進められるようにすることです。

これは TCPDF のフォークではなく、動作保証付きのクローンとして提供されるものでもありません。TCPDF の呼び出しシグネチャを維持した独立実装です。正確には、調査した約 120 の TCPDF 6.x メソッドのうち 94 を直接委譲によりカバーし、残りのメソッドには文書化された動作の差異がある ということです（/integrations/tcpdf-compat/method-coverage/ を参照）。

これは何か

移行支援ツール。 このパッケージは NextPDF 互換ファミリーの一部です。目的はレガシーな PDF ライブラリから脱却するまでの道筋を短くすることであり、恒久的な依存先になることではありません。モダンな API を採用するにつれて取り除いていく足場として扱ってください。
API サーフェスのアダプター。 TCPDF のクラス名、メソッド名、引数の順序、および 6.2.13 のデフォルト値を提供します。呼び出しは NextPDF\Core\Document インスタンスに委譲されます。
独立したクリーンルーム実装。 TCPDF のソースコード、ビルド成果物、フォントデータ、その他の著作権で保護され得る表現は、このパッケージにコピーも翻訳もされていません。TCPDF という名称は、相互運用性を識別する目的でのみ使用しています。正式な説明はパッケージの NOTICE ファイルにあります。

これは何ではないか

これは、バイト単位で同一の出力を生む「ドロップイン置き換え」では ありません。委譲されたメソッドについては見た目の結果に互換性がありますが、基盤となるエンジンが別個の独立した PDF 2.0 実装であるため、レンダリングされる PDF のバイト列は異なります。
これは「100% TCPDF 互換」では ありません。一部のメソッド群は、レガシーな引数を受け取るもののエンジンには反映しないか、まったく何もしません。これらは列挙され、テストされています。詳しくは /integrations/tcpdf-compat/method-coverage/ を参照してください。
これはそれ自体として署名製品やアーカイブ製品では ありません。デジタル署名と PDF/A アーカイブ適合は、商用の NextPDF エディションに限定されています。このドキュメントは、認証済み、保証付き、または法的に有効な署名に関するいかなる主張も行いません。

なぜ互換レイヤーを経由して移行するのか

大規模なアプリケーション全体で TCPDF の呼び出しをすべて一括で書き換えることはリスクが高く、段階的にリリースすることも困難です。互換レイヤーを使うと、次のことが可能になります。

依存先を入れ替えて既存のテストスイートを実行し、すでに変更なしで動作する部分を見つけます。
ストリクトモード を監査目的で使い、TCPDF の動作を正確に再現できない箇所をすべて列挙します。
アプリケーションを常にリリース可能な状態に保ちながら、それらの呼び出し箇所をモダンな NextPDF API へ一つずつ移行します。

最終的な到達点は、互換レイヤーを取り除いたモダンな NextPDF\Core\Document API です。完全な戦略については /integrations/tcpdf-compat/migration/ を参照してください。

NextPDF エンジンで得られるもの

TCPDF の呼び出しが委譲されると、PDF 2.0（ISO 32000-2）エンジン上で実行され、AES-256 標準ハンドラー暗号化を利用でき、アダプター全体で PHPStan Level 10 の型安全性が確保されます。出力は常に PDF 2.0 として書き出されます。アダプターは古い PDF バージョン向けにダウンターゲットすることはできません（/integrations/tcpdf-compat/method-coverage/ §4 を参照）。

TCPDF 6.2.13 に長く存在するいくつかの落とし穴に対して、アダプターは堅牢化を施しています。

レガシーの動作	アダプターの動作
`Error()` が `die()` を呼び出し、プロセスを暗黙のうちに終了させる	`Error()` が `RuntimeException` をスロー。観測可能でキャッチ可能
マークアップから PHP を実行できてしまう HTML メソッド	抜け道を無効化。マークアップによる PHP 実行は不可
`Output()` が直接出力し、ワーカーの出力バッファーを破損させ得る	安全な出力先ブリッジ経由の送信
保護されていない header/footer の再帰	再帰ガードあり

スコープとエディション

互換レイヤーは core ディストリビューションに同梱されています（nextpdf/compat-legacy で、nextpdf/core ^3.0 を必要とします）。標準ハンドラーによる暗号化は core で利用できます。デジタル署名と PDF/A アーカイブ適合には商用の NextPDF エディションが必要です。アダプターはそのエントリーポイントを公開していますが、core のパスは署名製品ではありません。正確な説明については /integrations/tcpdf-compat/security-and-operations/ を参照してください。

次に読むもの

/integrations/tcpdf-compat/install/ — パッケージをインストールしてエンジンとのリンクを検証します。
/integrations/tcpdf-compat/quickstart/ — 実行可能でテストに裏付けられた最初のドキュメント。
/integrations/tcpdf-compat/method-coverage/ — 各 TCPDF メソッドがこのアダプターで正確に何をするか。
/integrations/tcpdf-compat/migration/ — ファイルごとの移行戦略。
/integrations/tcpdf-compat/configuration/ — ストリクトモードとアダプターの設定。
/integrations/tcpdf-compat/production-usage/ — 負荷がかかる状況やワーカー内でのアダプター実行。
/integrations/tcpdf-compat/security-and-operations/ — 暗号化、署名のスタンス、堅牢化。
/integrations/tcpdf-compat/troubleshooting/ — 移行時によくある失敗と修正方法。
/integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ — ファサードをアプリケーションに組み込み、グローバルなクラスエイリアスを登録する。