NextPDF compat-legacy の TCPDF メソッドカバレッジ

概要

nextpdf/compat-legacy は互換レイヤーであり、TCPDF のフォークでも、動作互換性を保証するクローンでもありません。TCPDF 6.x の公開メソッド名、引数の順序、デフォルト値を、NextPDF コアエンジンの上に公開します。ほとんどの呼び出しは、NextPDF の Document 操作に直接マッピングされます。明確に定義された少数のメソッドは、NextPDF が反映しないレガシー引数を受け付けるか、まったく効果を持ちません。

このページは、メソッド単位の監査結果を読者向けに要約したものです。信頼できる、テストで検証済みのカバレッジマトリクスは、リポジトリ内の docs/TCPDF_COVERAGE.md にあります。このページとリポジトリ内のマトリクスが食い違う場合は、テストスイートで保証されているリポジトリ内のマトリクスが優先されます。

移行前に、このページで次の 1 つの問いを確認してください。コードベースが呼び出すすべての TCPDF メソッドについて、アダプターは実際に何をするのかという問いです。

カバレッジサマリー

この監査では、約 120 個の TCPDF 6.x 公開メソッドを調査しました。それぞれを、4 つのカテゴリーのいずれか 1 つに分類しています。

カテゴリー	件数	移行時の意味
ミラー — 完全委譲	94	呼び出しは NextPDF の `Document` メソッドに直接マッピングされます。文書化された引数については、動作に互換性があります。
サイレント無視 — 部分対応	15	メソッドは実行されて出力を生成しますが、1 つ以上の TCPDF 引数は効果を持ちません。文書化された動作上の差異です。
未実装 — 何もしない本体	4	メソッドはソース互換性のために存在しますが、何もしません。
適用外	7	その TCPDF メソッドは PDF 出力に影響しないため、意図的に除外されています。
追加されたモダン API ドリフトメソッド	17	NextPDF v5.1+ の Document メソッドをアダプターで公開し、API を混在させたコードがコンパイルできるようにしたものです。TCPDF 6.x に相当するものはありません。

これらの数値は docs/TCPDF_COVERAGE.md §Summary に基づいています。このマトリクスは tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php と tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php によって検証されています。

表現に関する注記。 このパッケージは「ドロップイン置き換え」や「100% TCPDF 互換」をうたっていません。約 120 個の TCPDF メソッドのうち、調査対象の 94 個を直接委譲でカバーします。残りのメソッドには、以下で説明する、文書化された動作上の差異があります。正確な表現は、既知かつテスト済みの互換サーフェスを備えた TCPDF 互換の代替 というものです。

メソッド数に関する注記

アダプターは、25 個の単一責任ごとのコンサーントレイト（src/Compat/Tcpdf/Concerns/）から構成されており、合計 273 個の公開メソッドを公開します。さらに、TCPDF クラス自体にも、少数のライフサイクルメソッドとエスケープハッチメソッドがあります。上記のカバレッジカテゴリーは、TCPDF 6.x API サーフェスの個別メソッド（約 120 個）を数えたものであり、アダプターの公開メソッド総数ではありません。この 2 つの数値は、API サーフェスのカバレッジと実装規模という、別々のものを測っています。パッケージの README.md に、より小さいトレイト数やメソッド数が引用されている場合は、docs/TCPDF_COVERAGE.md とこのページを信頼できる情報として扱ってください。README のサマリーは AdaptsDriftV51 トレイトより前の時点のものです。

1. ミラーメソッド — 互換性のある委譲

94 個のメソッドが、基盤となる NextPDF\Core\Document インスタンスに直接マッピングされます。エンジンが camelCase を使う箇所では、PascalCase の TCPDF 名が camelCase の NextPDF 名にマッピングされます。アダプターは前方互換性と後方互換性のため、どちらの綴りも受け付けます。

代表的なグループ（完全な表は docs/TCPDF_COVERAGE.md §1）:

TCPDF 領域	例となるメソッド	アダプタートレイト
ライフサイクル	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
ページ	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
テキスト	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
フォント	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
カラー	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
描画	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
変換	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
ナビゲーション	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

これらのメソッドについて観測される動作は、NextPDF が文書化している引数の範囲で TCPDF 6.x と互換性があります。アダプターは、バイト単位で同一の PDF 出力を保証しません。基盤となるエンジンは独立した PDF 2.0 実装であるため、表示結果が同等であっても、レンダリングされるバイトは異なります。テストがレンダリング内容ではなく PDF バイトの厳密な一致を検証している場合、それらのアサーションは再ベースライン化が必要になると見込んでください。推奨される再ベースライン化の戦略については /integrations/tcpdf-compat/migration/ を参照してください。

2. サイレント無視メソッド — 文書化された動作上の差異

これら 15 個のメソッドは実行されて出力を生成しますが、少なくとも 1 つの TCPDF 引数が、ソース互換性のために受け付けられたうえで無視されます。移行前に読むべき、最も重要なセクションです。呼び出しは失敗しませんが、TCPDF 本来の動作よりも静かに少ない処理しか行わないためです。

TCPDF メソッド	無視される引数	互換性のある代替手段
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	NextPDF の `image()` は file、x、y、width、height を取ります。クリック可能な画像にするには、画像を描画してから、同じ矩形の上に `Document::link()` を追加します。画像のマスクと代替画像はサポートされていません。
`writeHTML()`	ln, fill, reseth, cell, align	NextPDF の `writeHtml()` はコンテンツ専用です。レイアウトを制御するには、モダン API で HTML を配置済みブロックにラップしてください。
`writeHTMLCell()`	border（文字列形式）, ln, fill, reseth, autopadding	幅、高さ、位置、およびブール値の border は尊重されます。より高度なセルレイアウトにはマッピングがありません。
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	位置とサイズのみ。
`ImageSVG()`	link, align, palign, border, fitonpage	位置とサイズのみ。
`SetProtection()`	mode（非ゼロ）, pubkeys（非空）	NextPDF は標準ハンドラーに常に AES-256 を使用します。証明書ベースの暗号化には、アダプターで公開されているモダンな `setPublicKeyEncryption()` を使用してください（/integrations/tcpdf-compat/security-and-operations/ を参照）。
`Bookmark()`	style, color, x, isNamedDest	タイトル、レベル、y 位置は尊重されます。
`setDestination()`	page, x	名前と y 位置は尊重されます。
`Link()`	spaces	TCPDF 内部の空白追跡であり、エンジンに相当するものはありません。
`Annotation()`	Subtype を超えるオプションキー, spaces	種類、位置、テキストは尊重されます。
`SetLineStyle()`	幅を超える破線パターンの詳細	中核となる線のプロパティはマッピングされます。
`setAlpha()`	ブレンドモードマップの部分対応	一部のブレンドモード名には、エンジンに相当するものがありません。
`Polycurve()`	全引数リスト	デフォルトモードでは何もしません。エンジンに相当するものはありません。
`PieSectorXY()`	全引数リスト	部分的なマッピング（中心から外周への線が異なります）。
`RoundedRectXY()`	角ごとの半径	一様な角の半径のみ。

アダプターがこれらの差異をどのように表面化させるかは、strict モードに依存します（/integrations/tcpdf-compat/configuration/ を参照）。strict モードがオフのとき（後方互換性のあるデフォルト）、これらの呼び出しは静かに機能を落として処理されます。strict モードがオンのとき、引数を無視するすべての呼び出しは、無視された引数の正確なリストと移行ヒントを伴って TcpdfNotImplementedException をスローします。strict モードは監査ツールであり、本番設定ではありません。

strict モードの設計は、呼び出し側が自分の意図が尊重されなかったときにそれを観測できなければならない、という原則に従っています。OWASP ASVS 5.0 §16.5.3 は、アプリケーションが正常かつ安全に失敗し、フェイルオープン状態を防ぐべきだと述べています。引数のサイレントな喪失は脆弱性というより開発者体験上の落とし穴ですが、同じく明示的に失敗するという原則が当てはまります。固定されたクローズダイジェストはページのフロントマター citations にあります。

3. 未実装メソッド — 何もしない本体

4 個のメソッドは、レガシーソースがコンパイルできるように存在しますが、その本体は何もしません。strict モードがオンのとき、そのうち 3 個は TcpdfNotImplementedException をスローします。4 個目（Open()）は、レガシーコードから削除しても常に安全であるため、決してスローしない意図的で安全な no-op です。

TCPDF メソッド	動作	置き換え
`setSignature()`	no-op（実行可能なものは何も保存しません）。strict モードではスローします。	デジタル署名には、NextPDF の商用エディションが必要です。`CertificateInfo` 値オブジェクトを使うモダンな署名 API を使用してください — /integrations/tcpdf-compat/security-and-operations/. を参照してください。
`addEmptySignatureAppearance()`	no-op。strict モードではスローします。	`setSignature()` と同じ商用エディションゲートです。
`endPage()`	no-op。strict モードではスローします。	NextPDF はページのライフサイクルを自動的に管理します。呼び出しを削除してください。
`Open()`	安全な no-op。決してスローしません。	NextPDF は文書を自動的に開きます。呼び出しを削除しても常に安全です。

このアダプターを通じて、コアエンジンで署名を利用することはできません。アダプターはエンジンに委譲するモダンな署名エントリポイントを公開しますが、ベースラインの署名サポートは商用エディションにゲートされています。このドキュメントは、いずれのエディションについても、長期検証（LTV）プロファイルやタイムスタンプ付き署名プロファイルに関する主張を行いません — 正確で控えめな記述については /integrations/tcpdf-compat/security-and-operations/ を参照してください。

4. 適用外メソッド

7 個の TCPDF メソッドは PDF 出力に影響を与えないため、意図的に除外されています。これらを呼び出しても無害です。

TCPDF メソッド	除外の理由
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	状態はアダプターに保持されますが、文書の XMP メタデータには結び付けられていません。出力には現れません。
`setSRGBmode()`	NextPDF のカラーマネジメントは、このフラグとは独立しています。
`setPDFVersion()`	NextPDF は conformance/output プロファイルから PDF バージョンを選択するため、直接のセッターはありません。アダプターは通知を発行して続行します。
`setDocInfoUnicode()`	NextPDF は常に Unicode です。このフラグは設計上の no-op です。
`setDefaultMonospacedFont()`	エンジンに相当するものはありません。代わりに HTML/CSS のスタイリングが適用されます。
`setFontSubsetting()`	NextPDF は埋め込みフォントを常にサブセット化するため、このフラグは実質的に常にオンです。

PDF バージョンはエンジンによって固定されています。出力は PDF 2.0（ISO 32000-2）として書き出されます。ISO 32000-2 §7.5.2 は、適合ライターが文書のバージョンを — ファイルヘッダーまたはカタログの Version エントリで — 2.0 として識別することを規定しています。また、保存時にファイルのバージョンが古いバージョンへ下げられないことも規定しています。これはアダプターの動作と整合しています。setPDFVersion('1.4') のような呼び出しでは、このアダプターを通じて古い PDF バージョンをダウンターゲットすることはできません。固定されたクローズダイジェストは、ページのフロントマター citations にあります。

5. モダン API ドリフトメソッド

NextPDF コア v5.1+ の 17 個のメソッドがアダプターで公開されており（トレイト AdaptsDriftV51）、TCPDF API とモダン API を混在させたコードでもコンパイルできるようになっています。これらには TCPDF 6.x に相当するものはありません。例: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). これらは TCPDF 互換性契約の一部ではなく、モダン API として扱ってください。

6. 非推奨と置き換えのガイダンス

コードが次を呼び出している場合…	ステータス	代わりにこうする
`Error()`	動作が変更（堅牢化）	TCPDF の `die()` は、スローされる `RuntimeException` に置き換えられます。リスクのある呼び出しを `try`/`catch` でラップしてください。プロセスの終了に依存しないでください。
`setPDFVersion()`	適用外	削除します。出力は常に PDF 2.0 です。
`setUserRights()`	PDF 2.0 で非推奨	削除します。この呼び出しは `E_USER_DEPRECATED` 通知を発行し、無視されます。
`setSignature()`	コアでは未実装	商用エディションでモダンな署名 API に移行してください。
追加引数付きの `Image(...)`	サイレント無視	file、x、y、w、h に減らし、クリック可能な画像にするには `Document::link()` を追加してください。
`endPage()` / `Open()`	未実装 / no-op	削除します。

7. 安全な移行手順

パッケージをインストールし、コードを変更せずにアダプターに対して既存のスイートを実行してください — /integrations/tcpdf-compat/install/ と /integrations/tcpdf-compat/quickstart/. を参照してください。
専用の監査実行で（本番ではなく）strict モードを有効にしてください: $pdf->setStrictMode(true);。すべての TcpdfNotImplementedException を収集してください。それぞれが、無視された正確な引数と移行ヒントを示します。
スローされる各箇所について、無視された引数を削除するか、$pdf->getDocument() 経由でその呼び出しをモダン API に移行するかを選択してください。
PDF バイトの厳密な一致を検証するテストは再ベースライン化してください。代わりに、レンダリング内容や構造的なプロパティを検証してください。
strict モードをオフにして、監査済みのコードパスをデプロイしてください。リファクタリング中のリグレッションを捕捉するため、定期的な strict モードの CI ジョブを維持してください。

コードを含む完全な手順: /integrations/tcpdf-compat/migration/.