TCPDF 互換開発者ガイド

概要

互換アダプターは移行レイヤーです。レガシーな動作を隠すのではなく、見える形にすることを目的としています。アプリケーションを稼働させたまま、価値の高いパスをネイティブの NextPDF API へ移行するために使用します。

このガイドは、TCPDF 形式のレガシーコードを保守する場合、アダプターのカバレッジを追加する場合、またはネイティブの NextPDF API への段階的な移行を計画する場合に使用します。

アーキテクチャの境界

レイヤー	所有者	責務	ここに置かないもの
レガシーアプリケーション	アプリケーション	移行中も既存の TCPDF 形式の呼び出しを動かし続けます。	ネイティブの NextPDF API を使用すべき新しい PDF 機能。
アダプターシェル	`nextpdf/compat-legacy`	`TCPDF` 形式のクラスと共有互換性ステートを公開します。	大規模なメソッドファミリーや変換ロジック。
コンサーントレイト	`nextpdf/compat-legacy`	レガシーなメソッドファミリー（テキスト、フォント、画像、セキュリティ、フォーム、ページ）をグループ化します。	ファミリーをまたぐ出力ポリシー。
ブリッジクラス	`nextpdf/compat-legacy`	レガシーの引数、出力先、色、単位、フォーマットを変換します。	ビジネス固有の動作。
コアエンジン	`nextpdf/nextpdf`	ネイティブのドキュメントを生成します。	レガシー互換性に関する保証。

ランタイムのライフサイクル

ステージ	動作	開発者の対応
ブートストラップ	オプションのレガシーブートストラップが互換用の名前を公開します。	レガシーコードが TCPDF のシンボルを必要とする箇所でのみ使用します。
構築	レガシーのコンストラクター引数は、コアのドキュメント設定に適合されます。	移行中はコンストラクター入力を安定させておきます。
メソッド呼び出し	サポートされるメソッドは、コンサーンとブリッジを通じて NextPDF の動作にマッピングされます。	パリティを前提にする前にメソッドのカバレッジを確認します。
サポートされない機能	サポートされない動作では、明示的な互換性例外がスローされます。	呼び出しを置き換えるか、アプリケーションコードの背後に隔離します。
出力	出力ブリッジは、レガシーの出力先の動作を NextPDF の出力にマッピングします。	ファイル名とストレージのルートを検証します。

移行インベントリー

まず、アプリケーション内のすべての TCPDF メソッド呼び出しを収集します。動作を変更する前に、各呼び出しを分類します。

分類	意味	対応
サポートされるアダプターメソッド	メソッドはサポート対象として文書化され、テストもあります。	一時的に維持し、その領域を変更する際に移行します。
部分的なアダプターメソッド	メソッドは存在しますが、その動作はレガシーな TCPDF と完全には一致しません。	フィクスチャテストを追加し、出力を手動で検証します。
明示的にサポートされないメソッド	アダプターは互換性例外をスローします。	ネイティブの NextPDF に置き換えるか、機能を削除します。
ビジネス固有のラッパー	アプリケーションがすでに TCPDF 呼び出しをラップしています。	まずラッパーの内部を移行します。
コンプライアンスに影響する呼び出し	署名、暗号化、タグ付け、PDF/A、アクセシビリティ、または請求書フローに関わる呼び出し。	専用の検証とともに、ネイティブの NextPDF API へ移行します。

アダプターへの貢献パターン

互換性サポートは、その動作を担当する最小のメソッドファミリーに追加します。

変更の種類	実装する場所	必須のテスト
テキスト出力メソッド	`Concerns\AdaptsTextOutput` またはフォントコンサーン。	レガシーフィクスチャとネイティブ出力のアサーション。
ページまたはマージンのメソッド	ページ、位置決め、またはマージンのコンサーン。	座標変換とページステートのテスト。
画像または描画のメソッド	画像、描画、色、またはグラデーションのコンサーン。	入力検証と visual/structural 出力のテスト。
出力先	`OutputBridge`。	出力先のマッピングと安全でないパスのテスト。
サポートされない機能	例外ファクトリーまたはメソッドカバレッジ表。	例外の型とメッセージのテスト。

コンサーントレイトがそのファミリーを担当している場合、大規模なメソッドをアダプターシェルへ直接追加しないでください。

ネイティブ移行パターン

まずアダプターで安定させ、そのうえで安定したワークフローをネイティブ API へ移行します。

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

移行は、小さな動作変更の連続として扱います。1 つの高リスクなセクションをネイティブ API へ移行する間も、ページでは引き続きアダプターを使用できます。

拡張ポイント

拡張ポイント	用途	制約
`AdaptationConfig`	移行中のアダプターの動作を制御します。	デフォルト値は、レビュー済みで明示的な状態に保ちます。
コンサーントレイト	テキスト、フォーム、画像、セキュリティなどのメソッドファミリーをグループ化します。	アダプターシェルではなく、適切なコンサーンにメソッドを追加します。
ブリッジクラス	レガシー引数の形式をコアの値に変換します。	ブリッジの動作は移行テストでカバーし続けます。
`CompatAdapterInterface`	ツール向けのアダプターレベル抽象化。	新しいコードでは、ネイティブなコアコントラクトの代替として使用しないでください。
メソッドカバレッジ表	開発者向けのサポート台帳。	サポート状況が変わったら更新します。

移行ワークフロー

アダプターをインストールし、レガシーテストスイートを変更せずに実行します。
次に、メソッドカバレッジを開き、呼び出されているすべてのメソッドを分類します。
サポートされないメソッドを最初に置き換えます。
使用頻度の高いパス、またはコンプライアンスに影響するパスをネイティブのコア API へ移行します。
移行したすべてのメソッドファミリーにフィクスチャのカバレッジを追加します。
アプリケーションのどのエントリーポイントも依存しなくなったら、ブートストラップのエイリアスを削除します。

障害への対応

障害	対応すべき場所	推奨される対応
サポートされないメソッド	アダプター例外。	呼び出しを置き換えるか、アプリケーションアダプターの背後に分離します。
部分的なレイアウトのパリティ	移行テストと目視レビュー。	ロールアウト前に、許容する差異を文書化します。
安全でない出力先	`OutputBridge` とアプリケーションのストレージポリシー。	安全でないパスを拒否し、ネイティブの出力 API を優先します。
セキュリティ機能の不一致	ネイティブ移行計画。	規制対象の出力では、互換性のみの動作を出荷しないでください。
ブートストラップのエイリアスの衝突	アプリケーションのブートストラップ。	グローバルエイリアスを削除するか、レガシーのエントリーポイントにスコープを限定します。

安全なデフォルト

コンサーン	デフォルト	オーバーライドするタイミング
サポートされないメソッド	明示的な例外をスローします。	本番環境ではこれを弱めないでください。
レガシーのデフォルト	aggregate（集約）先は `LegacyDefaults` です。	既知の移行動作に限ってオーバーライドします。
出力マッピング	処理は `OutputBridge` を経由します。	移行後はネイティブの出力 API を使用します。
カバレッジのソース	メソッドカバレッジのページとテスト。	アダプターをアップグレードするたびに、カバレッジチェックを再実行します。
ストリクトモード	移行監査中は有効に保ちます。	文書化されたレガシー互換性期間に限って無効にします。

テストチェックリスト

移行した各メソッドファミリーについて、レガシーフィクスチャを維持します。
レガシーメソッドを置き換える前に、ネイティブの NextPDF テストを 1 つ追加します。
サポートされないメソッドが文書化された例外をスローすることをアサートします。
正確なバイト単位の一致が現実的な移行目標でない場合は、出力の構造を比較します。
アダプターメソッドを追加または変更した後に、メソッドカバレッジチェックを実行します。
レガシーコードが使用するすべての出力先について、ストレージパスのテストを追加します。