移行ガイド
移行ガイド
「移行ガイド」という見出しのセクションNextPDF は PHP 向けの PDF 2.0 エンジンです。すでに別のライブラリで PDF を生成している場合、移行ガイドでは、そのライブラリの API を NextPDF にマッピングし、遭遇する振る舞いの差異を文書化します。このページはリポジトリ横断のインデックスです。どのガイドがどのライブラリからの移行を対象にするか、各ガイドをどのリポジトリが所有するか、そしてすべてのガイドが共有する単一のモデルとは何かを記録します。
このページはインデックスであるため、いずれのガイドについても振る舞いに関する主張は行いません。各ガイドは、それぞれ独自のリポジトリによって所有されています。アグリゲーターが各ガイドをこのサイトに取り込みます。ガイドが追加されるまで、以下のリンクはプレースホルダーを指します。振る舞いに関するすべての主張はガイド自体に記載されており、リポジトリ内のテストまたは固定された ISO 32000-2 / CSS WG の条項によって裏付けられています。このページでは扱いません。
単一の移行モデル
「単一の移行モデル」という見出しのセクションすべての NextPDF 移行ガイドは、1 つの誠実なモデルを共有しています。各ガイドは、このモデルを前提にお読みください。
- バイト一致ではなく互換。 NextPDF と移行元のライブラリは、独立した実装です。移行するドキュメントは、ピクセル単位やバイト単位で同一になるのではなく、意図された機能において等価です。いずれのガイドも、ドロップイン置換や 100% の互換性を主張していません。
- カバレッジは主張ではなく、測定された数値です。 ガイドがカバレッジの数値を示している場合（たとえば TCPDF アダプター）、その数値は ISO/IEC 25023 条項 43 の意味における、リポジトリ内のマトリックスから導出された機能的完全性のメトリクスです。これは、カバー済みメソッドを測定した数であり、一律の保証ではありません。
- 各ガイドは、振る舞いの差異を明確に記載しています。 すべてのガイドには、明示的な差異の表と「未サポート/直接の等価物なし」のセクションが含まれています。差異は、文書化されたエンジンの特性であり、欠陥ではありません。
- レンダラーの変更には再レビューが必要です。 移行では、コードの変更に加えて、出力の再ベースライン化が必要です。各ガイドは、移行をテストする方法を説明しています。視覚的な受け入れはドキュメントごとに行われ、インテグレーターの責任です。
移行の形態
「移行の形態」という見出しのセクションガイドは 2 つの形態に分かれます。形態は、コード変更の規模を示します。
- API 書き換え移行には互換シムがありません。ガイドの動詞マッピングとオプションマップを使用して、すべての呼び出し箇所を書き換えます。 HTML-to-PDF ライブラリの移行 (
dompdf、mpdf) はこの形態です。これらは NextPDF Html パイプラインを直接ターゲットとします。 - ドロップイン後に移行する移行では、ソース互換に近いアダプターが提供されるため、最初の移行は依存関係の最小限の入れ替えで済みます。そこから、呼び出し箇所をモダンな API へ段階的に移行し、その後アダプターを廃止します。TCPDF の移行はこの形態であり、
nextpdf/compat-legacyアダプターを介して行われます。
ガイドと所有リポジトリのリファレンス
「ガイドと所有リポジトリのリファレンス」という見出しのセクション以下の各ガイドは、所有リポジトリの docs/public/ に存在し、アグリゲーターが各ページをこのサイトに取り込みます。所有リポジトリは、そのガイドの振る舞いに関する主張について権威ある情報源です。このインデックスは、ルーティングのみを記録します。
| 移行元 | ガイド | 形態 | 所有リポジトリ | ページ |
|---|---|---|---|---|
| Dompdf | Dompdf → NextPDF Html パイプライン | API 書き換え | nextpdf (コア) | Dompdf ガイド dompdf (アップストリームで計画中) |
| mPDF | mPDF → NextPDF コア | API 書き換え | nextpdf (コア) | mPDF ガイド mpdf (アップストリームで計画中) |
| TCPDF 6.x | TCPDF → NextPDF (compat-legacy アダプター経由) | ドロップイン後に移行 | nextpdf-compat-tcpdf リポジトリ、パッケージ nextpdf/compat-legacy | TCPDF ガイド tcpdf-compat (アップストリームで計画中) |
上記の dompdf と mpdf のガイドは、コアエンジンの API をターゲットとするため、コアリポジトリに置かれており、コアの examples/ がそれらを裏付けます。tcpdf-compat ガイドは compat-tcpdf リポジトリに存在します。これは、nextpdf/compat-legacy パッケージが TCPDF の振る舞い面と、ガイドを裏付けるアダプターのテストを所有しているためです。このインデックスは複数のリポジトリにまたがるため、ドキュメントネイティブに置かれており、そのいずれについても振る舞いに関する主張は行いません。
各ガイドの目的
「各ガイドの目的」という見出しのセクション- Dompdf → NextPDF (
dompdf(アップストリームで計画中)) — サーバーサイドでdompdf/dompdfを使用しているコードベース向けです。loadHtml/render/outputとOptionsのキーを NextPDF Html パイプラインにマッピングし、CSS 機能の期待値は Verified-only の CSS サポートマトリックスに委ねます。Dompdf クラスのシムはありません。すべての呼び出し箇所を書き換えます。 - mPDF → NextPDF (
mpdf(アップストリームで計画中)) —mpdf/mpdfを使用しているコードベース向けです。WriteHTML/Output/AddPageとコンストラクターの設定配列をコア API にマッピングします。ただし、フォント処理に差異があります。NextPDF は単一のフォントディレクトリと CSS マッチングを通じて resolve（解決）を行い、常にサブセット化します。Mpdf クラスのシムはありません。 - TCPDF → NextPDF (compat-legacy) (
tcpdf-compat(アップストリームで計画中)) — 最初の変更を最小限に抑えたい TCPDF 6.x のコードベース向けです。アダプターをインストールし、リポジトリ内のカバレッジマトリックスに対して strict モードで実際の使用面を監査し、呼び出し箇所をアダプターから移行したうえで、その上に PDF/UA-2 のタグ付き構造を追加します。これは、TCPDF にはなかった機能です。アダプターは足場であり、最終的な到達点でも、ドロップインの保証でもありません。
ガイドのリンクが解決される仕組み
「ガイドのリンクが解決される仕組み」という見出しのセクション上記の各 [[…]] プレースホルダーは、所有リポジトリの docs/public/migration/ 配下に存在するページへの前方参照であり、アグリゲーターがそのページをこのサイトに取り込みます。ターゲットのスラッグは、1 つの規則に従います。
/migration/<source>/この <source> トークンは、移行元ライブラリの短い名前です。上記のガイドリファレンス表に記載されているとおり、dompdf、mpdf、または tcpdf-compat のいずれかです。ターゲットページが aggregate（集約）されるまで、そのリンクはプレースホルダーであり、解決されません。このインデックスは、いずれのターゲットガイドについても振る舞いに関する主張は行いません。ルーティングと、共有される移行モデルのみを記録します。
- CSS サポートマトリックス —
dompdfとmpdfのガイドが CSS 機能の期待値を委ねる、Verified-only の権威ある情報源です。 - 統合クックブック — エコシステムの統合パッケージのためのリポジトリ横断インデックスです（これは別の関心事であり、対象はエンジンへの移行ではなく、エンジンへの接続です）。