TCPDF 互換 API リファレンス

概要

この nextpdf/compat-legacy パッケージは、メインクラス NextPDF\Compat\Tcpdf\TCPDF を 1 つ公開します。このクラスは TCPDF 6.x の公開 API をミラーリングしながら、最新の NextPDF エンジンでレンダリングします。さらに、補助的な要素も少数公開しています。グローバルクラスエイリアス用の LegacyBootstrap、AdaptationConfig/LegacyDefaults の構成サーフェス、内部ブリッジクラス（出力、コンストラクター、色、単位、ページフォーマット）、そして互換例外です。これは移行支援であり、恒久的な依存関係ではありません。レガシーメソッドの完全なステータスは、メソッドカバレッジ表に記載されています。このページでは、アプリケーションコードが意図的に依存すべきサーフェスを説明します。

ここから始めてください： このパッケージを初めて使う場合は、NextPDF\Compat\Tcpdf\TCPDF を構築し、通常の TCPDF 呼び出し（AddPage()、SetFont()、Cell()）を行い、Output($name, $dest) で完了してください。この 1 つのクラスが、以下のほぼすべての項目への入口となります。すぐに動かせる開始点については、共通タスクを参照してください。

共通タスク

これらは、このパッケージで実際によく行うタスクです。各ブロックはアダプターに対してソース検証済みで、そのまま実行できます。

おなじみの TCPDF 呼び出しで PDF を生成し、文字列として取得します（キュー、HTTP レスポンス、またはストレージでの利用向け）。

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetTitle('Invoice 1234');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$bytes = $pdf->Output('invoice.pdf', 'S');

動作：TCPDF 形式のアダプターを通じて PDF 2.0 ドキュメントを構築し、生のバイト列（%PDF...）を返します。これは、出力先 'S' が OutputBridge 経由で Document::getPdfData() へルーティングされ、エコー出力しないためです。ワーカーやコントローラー内でも安全に扱えます。

既存の new \TCPDF(...) コードは、起動時にグローバルエイリアスを一度登録するだけで、ソースを編集せずに実行できます。

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/legacy.pdf', 'F');

動作：enableAliases() は、\TCPDF（および \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES ヘルパー）を、それらの名前がまだ定義されていない場合に限り冪等に登録します。これにより、未変更のレガシーコードがアダプター上で実行されます。

黙って破棄されていた TCPDF パラメーターをすべて表面化し、移行を監査します。

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

動作：setStrictMode(true) を有効にすると、TCPDF の動作を再現できない呼び出しは TcpdfNotImplementedException をスローし、無視されたパラメーターを示します。これにより、暗黙的な品質低下を移行作業リストとして扱えます（これは監査パスでのみ実行し、本番環境では決して実行しないでください）。

メインアダプター

この表は、アダプターの正式なサーフェスです。構築するクラス（TCPDF）、その厳格モードおよびエスケープハッチメソッド、そして実装されるコントラクトを確認するときに参照してください。

シンボル	パラメーター	デフォルト動作	戻り値	スローまたは失敗する場合	注記
`NextPDF\Compat\Tcpdf\TCPDF`	`ConstructorBridge` を通じてレガシー TCPDF の形に従うコンストラクターパラメーター。	NextPDF ドキュメントを基盤とするアダプターの作成。	`TCPDF`	コンストラクターの検証またはサポート対象外機能の例外。	移行時の使用。新規のネイティブ NextPDF コードでは使用不可。
`TCPDF::getDocument()`	なし。	基盤となる NextPDF ドキュメントの返却。	`NextPDF\Core\Document`	想定なし。	レガシー呼び出しとネイティブ呼び出しを混在させる必要がある移行コード向けのエスケープハッチ。
`TCPDF::getUnitConverter()`	なし。	レガシー単位から作成されたコンバーターの返却。	`UnitConverter`	想定なし。	移行診断での使用。通常のアプリケーションコードでは使用不可。
`TCPDF::setStrictMode(bool $enabled)`	厳格モードフラグ。	サポート対象外の互換動作に対する明示的な失敗の有効化または無効化。	`static`	想定なし。	移行監査中は有効のまま維持。
`TCPDF::isStrictMode()`	なし。	現在の厳格モードフラグの返却。	`bool`	想定なし。	テストのアサーションで有用。
`TCPDF` レガシーメソッド	メソッドにより異なります。	サポートされるメソッドはコアドキュメント呼び出しへマッピング。サポート対象外のメソッドは明示的に失敗。	メソッドにより異なります。	`TcpdfNotImplementedException` または `UnsupportedFeatureException`。	メソッドに依存する前の、メソッドカバレッジの確認。
`CompatAdapterInterface::getDocument()`	なし。	`TCPDF` が実装するコントラクトメソッド。	`Document`	想定なし。	ツールからネイティブドキュメントへの到達を可能にするためのメソッド。
`CompatAdapterInterface::Output(string $name = '', string $dest = '')`	ファイル名とレガシーの出力先。	出力ブリッジへの委譲。	`string`	コアの書き込みまたは未サポートの出力先エラー。	レガシー TCPDF の出力エントリポイントのミラーリング。具体的な `TCPDF::Output` では `'doc.pdf'`/`'I'` のデフォルト値を指定。

レガシーメソッドグループ

この表は、アダプターがカバーする TCPDF メソッドファミリーのマップです。これを概観して、特定のレガシー呼び出しがおおよそどこに位置するかを把握してから、メソッドカバレッジで正確なステータスを確認してください。

グループ	代表的なシンボル	デフォルト動作	注記
ライフサイクルと出力	`Open()`, `Close()`, `Output()`, `getPDFData()`	ネイティブドキュメント上での TCPDF 形式のドキュメントライフサイクル維持。	移行後はネイティブの出力 API を優先。
メタデータ	`SetTitle()`, `SetAuthor()`, `SetSubject()`, `SetKeywords()`, `SetCreator()`	メタデータセッターの基盤ドキュメントへのマッピング。	メタデータ正規化はアプリケーションコード内で実施。
ページと位置指定	`AddPage()`, `setPage()`, `lastPage()`, `GetX()`, `SetXY()`	レガシーの単位と座標のネイティブページ操作への変換。	移行後の絶対位置指定の目視確認。
マージンとレイアウト	`SetMargins()`, `SetAutoPageBreak()`, `setCellPaddings()`, `getMargins()`	互換性状態の保存と、サポートされる値のマッピング。	複雑な TCPDF のページ区切り動作では、手動レビューが必要になる場合あり。
フォントとテキスト	`SetFont()`, `AddFont()`, `Cell()`, `MultiCell()`, `Write()`, `Text()`	一般的なテキスト操作のネイティブフォントおよびテキスト API へのルーティング。	CJK とエンコーディング動作の本番フォントでの確認。
HTML	`writeHTML()`, `writeHTMLCell()`, `fixHTMLCode()`	サポートされる HTML のネイティブ HTML パイプラインへの送信。	ネイティブレンダラーは完全な TCPDF HTML クローンではない点に注意。
画像と描画	`Image()`, `Line()`, `Rect()`, `Circle()`, `SetDrawColor()`	サポートされるグラフィックス操作のアダプターの関心事を通じたマッピング。	サポート対象外のベクターや特殊フォーマットは明示的に失敗。
ナビゲーションと注釈	`Bookmark()`, `AddLink()`, `SetLink()`, `Annotation()`	マッピング済み範囲での一般的なナビゲーション呼び出しの保持。	生成されたアウトラインとリンクの検証。
セキュリティと署名	`SetProtection()`, `setSignature()`, `setTimeStamp()`, `setUserRights()`	サポートされるレガシーのセキュリティ呼び出しのネイティブ機能へのブリッジ。	暗号出力は別個の検証ゲートとして扱うこと。
フォーム、テンプレート、変換	`TextField()`, `startTemplate()`, `StartTransform()`, `Rotate()`, `Scale()`	サポートされるサブセットの実装。サポート対象外の動作に対しては明示的に失敗。	展開前の、各呼び出しに対するメソッドカバレッジ照合と監査。

ブートストラップと構成

アダプターをアプリケーションの起動パスに組み込むとき（グローバルエイリアスの登録、およびレガシー定数と最新の AdaptationConfig の選択）には、この表を参照してください。

シンボル	パラメーター	デフォルト動作	戻り値	スローまたは失敗する場合	注記
`LegacyBootstrap::enableAliases()`	なし。	互換エイリアスの一度だけの登録。	`void`	オートロードまたは環境のエラー。	レガシーコードが TCPDF 名のグローバルな存在を前提とする場合のみ使用。
`LegacyBootstrap::isRegistered()`	なし。	エイリアスが登録済みかどうかの報告。	`bool`	想定なし。	ブートストラップのテストで有用。
`LegacyBootstrap::resetForTesting()`	なし。	テスト用の登録状態クリア。	`void`	想定なし。	テスト専用ヘルパー。
`AdaptationConfig`	アダプターのフラグと移行制御。	省略時はパッケージのデフォルトを使用。	`AdaptationConfig`	無効なオプション値。	移行監査中は構成を明示的に維持。
`AdaptationConfig::fromLegacyConstants()`	なし。	既知のレガシー定数の読み取りによる構成の構築。	`AdaptationConfig`	無効なレガシー定数値。	大規模なレガシーアプリケーション向けの過渡的ヘルパー。
`LegacyDefaults`	なし。	デフォルトのレガシー値の提供。	デフォルト値のセット。	想定なし。	互換性デフォルトの一元的な場所。

ブリッジとヘルパー

これらは、アダプターが使用する内部変換クラスです。この表は主に、アダプターのカバレッジに貢献するときや、レガシー引数がどのように変換されたかを診断するときに参照してください。日常的なアプリケーションコード向けのものではありません。

シンボル	パラメーター	デフォルト動作	戻り値	スローまたは失敗する場合	注記
`ConstructorBridge`	レガシーコンストラクターの引数リスト。	レガシーオプションの NextPDF 構成への正規化。	コンストラクターのデータ。	無効なレガシー引数値。	アダプターによる内部使用。
`CellParameterAdapter`	TCPDF のセルパラメーター。	レガシーの位置引数のコアテキストレイアウトオプションへのマッピング。	変換されたパラメーター。	無効な寸法または配置。	新規コードではネイティブのコアメソッドを優先。
`OutputBridge::dispatch(Document $document, string $filename, string $dest)`	ネイティブドキュメント、ファイル名、レガシーの出力先。	inline/download/save 動作の NextPDF 出力 API へのマッピング。	`string`	コアの書き込みエラー。未サポートの出力先。	出力前のファイル名とストレージルートの検証。
`OutputBridge::resolveDestination(string $dest)`	レガシーの出力先コード。	出力先のネイティブ出力先への変換。	`OutputDestination`	未サポートの出力先エラー。	出力先マッピングの一元管理。
`ColorTranslator`	TCPDF の色引数。	レガシーの色形式の正規化。	コアの色値。	無効な色値。	色と描画の関心事での使用。
`PageFormatResolver`	レガシーのページフォーマット入力。	既知の名前のコアページサイズへのマッピング。	ページフォーマット値。	不明なフォーマット。	移行後は明示的なネイティブページサイズを使用。
`UnitConverter`	レガシーの測定値と単位。	コア単位への変換。	数値。	無効な単位。	レガシーのレイアウト動作保持に有用。

例外

移行の呼び出しが明示的に失敗したときは、この表を使用してください。どの例外が「未実装」を意味し、どれが「既知だがサポート対象外」を意味するか、そしてそれぞれからどう回復するかを示します。

シンボル	意味	回復方法
`TcpdfNotImplementedException`	要求されたレガシーメソッドを、アダプターが意図的に未実装としている状態。	ネイティブの NextPDF API への呼び出し置換、または依存関係の削除。
`TcpdfNotImplementedException::forSilentIgnore()`	以前は無視されていたレガシー呼び出しを、移行を明確にするために表面化した状態。	明示的な no-op 動作を許容できるかどうかの判断。
`TcpdfNotImplementedException::forUnimplemented()`	レガシー呼び出しに、実装済みのアダプターパスがない状態。	呼び出しの置換、または移行コードの背後への分離。
`UnsupportedFeatureException`	既知のレガシー機能だが、アダプターの境界内ではサポートされていない状態。	移行ガイダンスの確認、および機能のアプリケーションアダプター背後への分離。
`UnsupportedFeatureException::forMethod()`	メソッド固有のサポート対象外機能エラーの作成。	一貫した失敗メッセージを保つための、互換性への貢献時の使用。

開発上の注記

アダプターは移行ツールとして扱ってください。新規コードではコアの NextPDF API を直接対象にしてください。
サポート対象外の動作は明示的に失敗させてください。アプリケーションがそのリスクを明示的に受け入れる場合を除き、互換例外をキャッチして部分的なドキュメントのまま処理を続行しないでください。
移行時の変更は小さく保ち、各レガシーメソッドをカバレッジ表に照らして検証してください。