mPDF から NextPDF への移行

概要

このガイドでは、mPDF ベースのコードベースを NextPDF コアへ移行する方法を説明します。mPDF の中心的な操作は WriteHTML() であり、これは Document::writeHtml() に直接対応します。主な作業は、コンストラクター設定配列の対応付け（mPDF は new Mpdf([...]) に渡す 1 つの連想配列ですべてを設定します）と、フォント処理の差分への対応です。NextPDF と mPDF は独立したエンジンであるため、移行後のドキュメントは mPDF の出力と 互換性があります が、バイト単位では同一になりません。このガイドでは、操作の対応付け、設定配列の対応付け、フォントの差分、CSS サポートの差分、挙動の違い、そして安全な移行手順を扱います。

この CSS サポートマトリクスが、検証済みの HTML/CSS 機能を示す唯一の根拠です。このガイドは挙動を説明するものであり、mPDF との視覚的な同等性を主張するものではありません。

インストール

composer require nextpdf/core:^3

移行期間中は mpdf/mpdf をインストールしたままにしておきます。最終的な切り替え後に削除してください（安全な移行手順を参照）。

概念的な概要

mPDF の Mpdf オブジェクトは、1 つの大きなファサードです。コンストラクター配列で設定し、WriteHTML() とページ処理の操作（AddPage、SetHTMLHeader、SetHTMLFooter）で動作させます。NextPDF は設定を不変の NextPDF\Core\Config 値オブジェクトへ分離し、コンテンツは Document::writeHtml() で扱います。コンストラクターの「モード」文字列はありません。NextPDF は渡された HTML を解析し、その後 save()、output()、または getPdfData() でドキュメントを出力します。

フォント: mPDF はフォントディレクトリに加えて、fontdata マップと「コアフォント」のフォールバックセットを同梱します。NextPDF は、単一のフォントディレクトリと CSS の font-family マッチングを通じてフォントを解決（resolve）し、埋め込みフォントを常にサブセット化します（ISO 32000-2 §9、iso32000_2_sec9#x1.x45.p7）。フォントの matching/fallback はエンジン固有であるため（CSS Fonts 4 §5.5、css_fonts_4#x1.x5.x5.x1.p13）、グリフの置換が異なる場合があります。これが主な可視差分であり、フォント処理の差分で扱います。

API のサーフェス

NextPDF の HTML API については、Html モジュールのリファレンスを参照してください。中心となるエントリーポイントは、Document::createStandalone()、Document::writeHtml(string $html): static、Document::writeHtmlCell(...)、Document::addPage()、Document::output(?string, OutputDestination)、Document::save(string $path): void、Document::getPdfData(): string、そして NextPDF\Core\Config 値オブジェクトです。

API 動詞の対応付け

以下の mPDF の公開メソッド名は、上流の公開リポジトリ（mpdf/mpdf、development）に対して確認済みです。リポジトリ内の _source-sidecar-upstream-api.md 来歴サイドカーを参照してください。上流のドキュメント本文は複製していません。

mPDF	NextPDF	備考
`new Mpdf([...])`	`Document::createStandalone($config)`	mPDF の設定配列は `NextPDF\Core\Config` に対応付けられます。設定の対応付けを参照してください。長時間稼働するワーカーでは `DocumentFactory` を使用してください。
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	直接対応。mPDF の 2 番目の `$mode` 引数（完全なドキュメント/CSS のみ/要素）には NextPDF に相当するものがありません。完全な HTML を渡してください。
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	位置・サイズを指定した HTML 領域。x/y/width/height の引数を対応付けます。
`$mpdf->AddPage(...)`	`$doc->addPage()`	mPDF の呼び出しごとの orientation/format/余白オーバーライドは、NextPDF では引数ではありません。代わりに、呼び出しの間でドキュメントモデルを変更してください。
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	Layout API による header/footer	mPDF の running HTML ヘッダーは、本文先頭のインライン HTML ではなく、NextPDF の header/footer メカニズムに対応付けられます。
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	mPDF の出力先文字（`I`/`D`/`F`/`S`）は、`OutputDestination` 列挙型（`Inline`/`Download`、file は `save()` 経由、string は `getPdfData()` 経由）に対応付けられます。
`$mpdf->Output('','S')`	`$doc->getPdfData()`	バイト列を返します。
`$mpdf->Output($path,'F')`	`$doc->save($path)`	ファイルパスに書き込みます。
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	ISO 32000-2 §14 の情報辞書 / XMP に格納されます（`iso32000_2_sec14#x1.x5.p5`）。
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)`（セキュリティ API）	権限はアクセス制御ではなく、リーダーの協力に依存します。セキュリティに関する注意事項を参照してください。

コードサンプル — クイックスタート

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// mPDF:
//   $mpdf = new \Mpdf\Mpdf();
//   $mpdf->WriteHTML('<h1>Invoice</h1>');
//   $mpdf->Output('out.pdf', \Mpdf\Output\Destination::FILE);

// NextPDF — default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->writeHtml('<h1>Invoice</h1>');
$doc->save(__DIR__ . '/out.pdf');

echo "Wrote out.pdf\n";

コードサンプル — 本番

これは、このガイドのフォント処理の概念を裏付ける実行可能なサンプルである examples/04-text-and-fonts.php と整合しています。明示的なページサイズ、余白、そしてフォント選択を行う本文コンテンツを使用しています。

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// Equivalent of: new Mpdf(['format'=>'A4','margin_left'=>20, ...]).
// Margin constructor order is (top, right, bottom, left) — NOT L,R,T,B.
$config = new Config(
    pageSize: new PageSize(595.276, 841.890, 'A4'),
    margins: new Margin(16.0, 20.0, 16.0, 20.0), // top,right,bottom,left in points
    fontsDirectory: __DIR__ . '/fonts',
);

$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->addPage();

$html = <<<'HTML'
<h1 style="font-family:'DejaVu Sans';color:#1E3A8A;">Quarterly Report</h1>
<p>Body text resolves through CSS font-family matching against the configured
fonts directory. mPDF's fontdata map has no direct analogue — register the
family via CSS and the fonts directory instead.</p>
HTML;

$doc->writeHtml($html);

// Equivalent of $mpdf->Output('report.pdf', Destination::DOWNLOAD):
$doc->output('report.pdf', OutputDestination::Download);

エッジケースと注意点

$mode 引数（WriteHTML の引数）。 mPDF の WriteHTML($html, $mode)（2 = CSS のみ、1 = 要素）には相当するものがありません。渡す HTML に CSS をインライン化してください。「CSS を書いてから本文を書く」という手順はありません。
AddPage ごとのオーバーライド。 mPDF では、AddPage() の引数を介してドキュメントの途中で format/orientation を変更できます。NextPDF の addPage() はそのような引数を取りません。サイズの変更はページ呼び出しではなく、ドキュメントを通じて行います。
ヘッダー/フッターの HTML。 mPDF の running ヘッダーは、別途登録される HTML フラグメントです。本文に貼り付けないでください。NextPDF の header/footer メカニズムに対応付けます。
フォント名。 mPDF はフォント名を fontdata/core-font テーブルを通じて正規化します。NextPDF は CSS の font-family をフォントディレクトリと照合します。暗黙的に解決されていた mPDF のエイリアスには、明示的な @font-face/family 宣言が必要になる場合があります。
出力先文字。 'I'/'D'/'F'/'S' は受け付けられません。OutputDestination 列挙型、または save()/getPdfData() を使用してください。

パフォーマンス

writeHtml() はシングルパスです（ADR-001）。ピークメモリは保持された DOM ではなく、ドキュメントサイズに比例します。このガイドのサンプルの予算: wall_ms: 2000, peak_mb: 128。長いドキュメントでは、1 つの巨大な文字列ではなく addPage() でコンテンツをページ分割してください。これは mPDF の $mode によるチャンク分割にも当てはまる助言ですが、NextPDF ではページモデルを通じて表現されます。

セキュリティに関する注意事項

権限はリーダーの協力に依存します。 SetProtection() → setEncryption() は機密性を提供しますが、アクセス制御は提供しません。ISO の権限ビットは、協力するリーダーに依存します。暗号化をアクセス制御としてユーザーに提示しないでください。
メタデータ。 SetTitle() とドキュメント情報は、ISO 32000-2 §14 の情報辞書 / XMP に格納されます（iso32000_2_sec14#x1.x5.p5）。そこに秘密情報を保存しないでください。
NextPDF はドキュメント内のスクリプトを実行しません。ここでスクリプトを有効にする mPDF のディレクティブはありません。

準拠

記述	仕様	条項
フォントは embedded/subset フォントプログラムとして書き込まれます。	ISO 32000-2	§9
ページの format/margins は、ページ境界ボックスに対応付けられます。	ISO 32000-2	§7
タイトル / 保護メタデータは、情報辞書 / XMP に格納されます。	ISO 32000-2	§14
フォントのマッチング / フォールバックはエンジン固有です。	CSS Fonts 4 の仕様	§5.5

NextPDF は ISO 32000-2 コンテンツを生成します。mPDF との視覚的な同一性は主張しません。レンダラーを変更する場合は、出力の再レビューが必要です。

商用コンテキスト

該当しません。コアは、ここで説明する mPDF の移行パスをカバーします。

移行の詳細（R6 必須セクション）

対象読者

サーバーサイドの HTML→PDF のために mpdf/mpdf を運用しているチームが対象です。使用しているサーフェスが new Mpdf([...]) + WriteHTML + Output（および任意の header/footer）であれば、動詞の対応付けと設定の対応付けが対応範囲をカバーします。

スコープ

スコープ内: Mpdf コンストラクター設定配列、WriteHTML/Output/AddPage、headers/footers、フォント、保護、メタデータ。スコープ外: mPDF の内部クラス、および QR/バーコード/透かしのヘルパーサーフェス（それらは対応する NextPDF モジュール（Barcode、Graphics）に対応付けてください。ここでは扱いません）。

互換性マップ

挙動の互換性であり、ドロップインのシムではありません。Mpdf クラスのシムはありません。すべての呼び出し箇所を書き換える必要があります。CSS 機能の期待値は、CSS サポートマトリクスの検証済み行です。

コンストラクター設定配列の対応付け

mPDF の設定キーは、上流の公開リポジトリ（mpdf/mpdf、development）に対して確認済みです。上流のドキュメント本文は複製していません。

mPDF 設定キー	NextPDF	備考
`mode`	（相当なし）	mPDF のモード文字列（`'utf-8'`、`'c'`、`'+aCJK'`、…）は font/script の挙動を選択します。NextPDF は常に Unicode です。CJK はモードではなく、フォント選択で処理されます。このキーは削除してください。
`format`	`Config->pageSize`（`PageSize` VO）	名前付きフォーマットは明示的なポイント寸法になります。配列 `[w,h]` は `PageSize` に対応付けられます。
`orientation`	入れ替え: `PageSize` の width/height	方向フラグはありません。横向き = 幅 > 高さ。
`default_font_size`	CSS の基本 font-size	コンストラクターキーではなく、基本スタイルシートで設定します。
`default_font`	CSS の `font-family` / 登録済みフォント	デフォルトのファミリーは CSS / フォント登録を介して設定します。
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins`（`Margin` VO、単位はポイント）	1 つの `Margin` 値オブジェクトです。そのコンストラクターの順序は、mPDF のキー順ではなく `Margin(top, right, bottom, left)` です（`src/ValueObjects/Margin.php` で確認してください）。
`margin_header` / `margin_footer`	Layout API による header/footer オフセット	コンストラクターキーではなく、NextPDF の header/footer 設定に対応付けます。

フォント処理の差分

単一のフォントディレクトリ。 mPDF のフォントディレクトリのリスト + fontdata マップ + コアフォントのフォールバックは、Config->fontsDirectory と CSS の font-family マッチングに集約（aggregate）されます。
常にサブセット化。 NextPDF は埋め込みフォントを常にサブセット化します（ISO 32000-2 §9、iso32000_2_sec9#x1.x45.p7）。mPDF のサブセットフラグには相当するものがなく、必要ありません。
マッチングはエンジン固有。 フォントの matching/fallback はエンジンによって異なります（CSS Fonts 4 §5.5、css_fonts_4#x1.x5.x5.x1.p13）。mPDF のフォントエイリアスには、明示的な @font-face または正確なファミリー名が必要になる場合があります。移行後にグリフのレンダリングを再ベースライン化してください。置換の違いは欠陥ではなく、想定される動作です。

挙動の違い

フォントの置換（上記参照） — 主な目に見える差分。
$mode が WriteHTML にない — インライン CSS を含む完全な HTML を渡してください。
AddPage ごとのフォーマットオーバーライドがない — サイズの変更はドキュメントを通じて行います。
権限はリーダーの協力に依存する（セキュリティに関する注意事項を参照）。
独立したレイアウトエンジン — 行の折り返し / ページネーションは、内容が密なドキュメントで異なります。視覚的な差分を再ベースライン化してください。

これらは文書化された挙動の違いであり、いずれのエンジンの欠陥でもありません。

サポート対象外 / 直接の相当なし

mode コンストラクター文字列 — モデル化されていません（常に Unicode）。
呼び出しごとの AddPage() の format/orientation/margin 引数 — NextPDF では引数ではありません。
mPDF の fontdata マップ — フォントディレクトリ + CSS マッチングに置き換えられます。
mPDF の 'I'/'D'/'F'/'S' 出力先文字 — OutputDestination 列挙型 + save()/getPdfData() に置き換えられます。

安全な移行手順

追加: nextpdf/core を mpdf/mpdf と並行して追加します（当面は mPDF を維持）。
リスクの低いドキュメントを 1 つ選びます。 new Mpdf([...]) を設定の対応付けを介して変換し、WriteHTML/Output を動詞の対応付けを介して変換します。
ドキュメントが使用するフォントを Config->fontsDirectory に登録し、mPDF のエイリアスには明示的な @font-face/family 宣言を追加します。
同じ入力に対して両方の PDF を生成し、視覚的に差分を取ります。差分（フォントの置換、行の折り返し）は独立したエンジンでは想定されるものです。ドキュメントごとに許容してください。
header/footer の HTML を NextPDF の header/footer メカニズムに対応付けます。
リスクの低いものから順に、ドキュメントごとに繰り返します。最後の切り替えまで mPDF をインストールしたままにしておきます。
最終的な切り替え後に、mpdf/mpdf を composer.json から削除します。

移行のテスト

コードを変更する前に、代表的なドキュメントの mPDF 出力をスナップショットします（ゴールデン入力。バイト列は異なります）。
移行したドキュメントごとに、独自の受け入れチェック（視覚的な差分 + テキスト抽出）で検証してください。NextPDF のフォント/HTML の挙動は、examples/04-text-and-fonts.php と examples/08-html-basic.php、およびコアの tests/ Html/Font スイートで検証されています。移行の受け入れはドキュメント固有であり、利用側の責任です。
移行したドキュメントごとに回帰テストを追加します。

エビデンス / トレーサビリティ

このページ上の NextPDF の挙動に関するすべての記述は、リポジトリ内のテスト、サンプル、ソースのシグネチャ、または ADR によって裏付けられています。あるいは、それが PDF フォーマットのプロパティである場合は、RAG でピン留めされた ISO 32000-2 / CSS の条項（フロントマターの citations: と準拠表にあるもの）によって裏付けられています。mPDF の挙動は「独立したエンジン — 文書化された違いを想定」としてのみ主張されており、リポジトリ内の成果物が証明しない同等性は主張していません。

NextPDF の挙動に関する主張	リポジトリ内のエビデンス（パス）
`WriteHTML()` は `Document::writeHtml(string $html): static` に直接対応します。	`src/Core/Concerns/HasTextOutput.php`（`writeHtml()`）。`examples/08-html-basic.php`。
`WriteFixedPosHTML(...)` は `writeHtmlCell(...)` に対応付けられます。	`src/Core/Concerns/HasTextOutput.php`（`writeHtmlCell()`）。
`createStandalone()` のデフォルトページは A4 縦向き（`595.276 × 841.890 pt`）です。	`src/Core/Config.php`（デフォルトの `PageSize`）。`tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`。
`Margin` のコンストラクターの順序は `(top, right, bottom, left)` です。	`src/ValueObjects/Margin.php`（昇格プロパティの順序）。
出力先は `NextPDF\Contracts\OutputDestination` 列挙型です。`'I'/'D'/'F'/'S'` は受け付けられません。	`src/Contracts/OutputDestination.php`（ケース `Inline`/`Download`/`File`/`String`）。`tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php`。
`Output('','S')` → `getPdfData()`。`Output($path,'F')` → `save($path)`。	`src/Core/Concerns/HasOutput.php`（`getPdfData()`、`save()`、`output()`）。
`SetProtection()` は `setEncryption(...)` に対応付けられます。権限はリーダーの協力に依存します。	`src/Core/Concerns/HasSecurity.php`（`setEncryption()`）。ISO 32000-2 §14（フロントマターの `citations:`）。
`SetTitle()` → `setTitle()`。メタデータは情報辞書 / XMP に格納されます。	`src/Core/Concerns/HasMetadata.php`（`setTitle()`）。`tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`。ISO 32000-2 §14（フロントマターの `citations:`）。
フォントは常にサブセットプログラムとして埋め込まれます。	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`。`examples/04-text-and-fonts.php`。ISO 32000-2 §9（フロントマターの `citations:`）。
フォントのマッチング / フォールバックはエンジン固有です（置換の差分）。	CSS Fonts 4 §5.5（フロントマターの `citations:` + 準拠）。
`writeHtml()` はシングルパスです。ピークメモリはドキュメントサイズに比例します。	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`。

ロールバック

両方のパッケージは最終的な切り替えまでインストールされたままになるため、呼び出し箇所ごとのロールバックは、その呼び出し箇所を mPDF のパスに戻すことです。最終的な切り替え後のロールバックは、mpdf/mpdf とそれ以前のコードをバージョン管理から復元することです。データの移行は伴いません。

パフォーマンスに関する考慮事項

詳しくはパフォーマンスを参照してください。シングルパスモデルにより、mPDF の保持バッファのコストがなくなります。ドキュメントごとの新しいコストは積極的なフォント解決（手順 3）であり、これはフォントディレクトリを介してキャッシュ可能です。

よくある落とし穴

mode キーを残し、それによる CJK の挙動を期待すること（このキーは削除されます。CJK はフォント選択です）。
WriteHTML($html, 2)（CSS のみのモード）を渡すこと。代わりに CSS をインライン化してください。
header/footer の HTML を本文に貼り付けること。
明示的なファミリーなしで、mPDF のエイリアスに同じフォントを期待すること。
byte/pixel-identical な出力を期待すること（独立したエンジン — このガイドはドロップインや 100% の互換性を一切主張しません）。
CSS サポートマトリクスを参考情報として扱うこと — これは検証済み機能の唯一の根拠です。