DomPDFからの移行

このガイドでは、DomPDF（dompdf/dompdf）からTCPDF-Nextへの移行を支援します。2つのライブラリは根本的に異なる設計哲学を持っています -- DomPDFはHTML/CSSからPDFへのレンダラーですが、TCPDF-Nextは強力なHTMLレンダリングエンジンを備えたPDFネイティブライブラリです。

DomPDFアプローチ vs TCPDF-Nextアプローチ

DomPDFはPDF生成をHTMLレンダリングとして扱います。HTMLとCSSを書くと、DomPDFがPDFに変換します。便利ですが、CSSで表現できる範囲に限られ、デジタル署名、暗号化、PDF/A準拠などのネイティブPDF機能にはアクセスできません。

TCPDF-Nextは2つのアプローチを提供します：

アプローチ	説明	最適な用途
Core API	PHPメソッドによる直接PDF構築	精密なレイアウト、フォーム、グラフィックス、署名
Artisan HTMLレンダラー	DOMベースHTML/CSSレンダラー（`HtmlRenderer`）	HTML重視のコンテンツ、DomPDFからの移行

ほとんどのDomPDF移行では、Artisan HTMLレンダラーを使用してください -- 最小限の変更で既存のHTMLテンプレートを受け付けます。

APIマッピング

DomPDF	TCPDF-Next	備考
`new Dompdf($options)`	`PdfDocument::create()->build()`	フルエントビルダー
`$dompdf->loadHtml($html)`	`$renderer->writeHtml($html)`	同じHTMLが動作
`$dompdf->loadHtmlFile($url)`	`$renderer->writeHtmlFile($path)`	デフォルトでローカルファイルのみ
`$dompdf->setPaper('A4', 'portrait')`	`->setPageFormat(PageFormat::A4)`	Enumベース
`$dompdf->render()`	`save()` / `toString()`で自動実行	明示的なレンダリング手順不要
`$dompdf->output()`	`$pdf->toString()`	バイナリ文字列を返却
`$dompdf->stream('file.pdf')`	フレームワークレスポンスヘルパー	下記の例を参照
`$options->set('defaultFont', ...)`	`$renderer->setDefaultFont(...)`
`$options->set('isRemoteEnabled', true)`	`ResourcePolicy::allowDomain(...)`	明示的な許可リスト
`$options->set('chroot', $dir)`	`ResourcePolicy::allowLocalDirectory(...)`	よりきめ細かな制御

基本的な移行サンプル

DomPDF（変更前）：

php

use Dompdf\Dompdf;
use Dompdf\Options;

$options = new Options();
$options->set('defaultFont', 'Helvetica');
$options->set('isRemoteEnabled', true);

$dompdf = new Dompdf($options);
$dompdf->loadHtml($html);
$dompdf->setPaper('A4', 'portrait');
$dompdf->render();
file_put_contents('output.pdf', $dompdf->output());

TCPDF-Next（変更後）：

php

use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Html\HtmlRenderer;

$pdf = PdfDocument::create()
    ->setPageFormat(PageFormat::A4)
    ->build();

$renderer = new HtmlRenderer($pdf);
$renderer->setDefaultFont('Helvetica', size: 12);
$renderer->writeHtml($html);

$pdf->save('output.pdf');

CSSサポート比較

CSS機能	DomPDF	TCPDF-Next
ボックスモデル（margin、padding、border）	はい	はい
Float	部分的	部分的
Flexbox	いいえ	いいえ
Grid	いいえ	いいえ
`position: absolute/relative`	部分的	はい
`@font-face`	はい	はい
`page-break-before/after`	はい	はい
`background-image`	部分的	はい
`border-radius`	いいえ	はい
`opacity`	はい	はい
CSS変数（`--custom`）	いいえ	いいえ
メディアクエリ	いいえ	`@media print`のみ
`table`レイアウト	はい	はい（改善済み）

TIP

TCPDF-NextのHTMLレンダラーはほとんどのCSS 2.1プロパティと一部のCSS 3プロパティをサポートしています。FlexboxとGridはサポートされていません -- 複雑なレイアウトにはテーブルを使用してください。CSSレンダリングの違いがある場合は、HTMLレンダラーのドキュメントを確認してください。

CoreとArtisanの使い分け

シナリオ	推奨アプローチ
既存HTMLテンプレートの移行	Artisan HTMLレンダラー
ピクセルパーフェクトレイアウト（請求書、証明書）	Core API
デジタル署名が必要	Core API（署名は両方で動作しますが、Coreがより制御可能）
PDF/A準拠	どちらでも（両方ともPDF/A-4をサポート）
バーコード / QRコード	Core API（ネイティブベクターレンダリング）
入力可能フィールド付きフォーム	Core API
HTMLからの単純なレポート	Artisan HTMLレンダラー

パフォーマンス比較

メトリック	DomPDF	TCPDF-Next	改善
単純な1ページPDF	62.1 ms	8.2 ms	7.6倍高速
20ページレポート	891 ms	187 ms	4.8倍高速
ピークメモリ（1ページ）	22.1 MB	4.2 MB	5.3倍削減
ピークメモリ（20ページ）	89.7 MB	12.4 MB	7.2倍削減
出力ファイルサイズ（1ページ）	31.8 KB	12.4 KB	2.6倍小型

詳細な方法論と追加テストケースについては、パフォーマンスベンチマークをご覧ください。

移行後の新機能

DomPDFがサポートしていない、TCPDF-Nextで利用可能な機能：

デジタル署名 -- ハードウェアセキュリティモジュールサポート付きのPAdES B-BからB-LTA。
AES-256暗号化 -- パスワードおよび証明書ベースのドキュメント保護。
PDF/A-4 -- 完全なアーカイブ準拠（ISO 19005-4）。
タグ付きPDF / PDF/UA -- スクリーンリーダー向けアクセシビリティ。
ネイティブバーコード -- QR、Data Matrix、Code 128、EANなどをベクターグラフィックスとして。
フォームフィールド -- 入力可能なテキストフィールド、チェックボックス、ドロップダウン。
クロスリファレンスストリーム -- 最新のPDF構造によるより小さなファイルサイズ。

さらに詳しく

APIマッピングテーブル -- 詳細なメソッドマッピング
ベンチマーク -- 完全なパフォーマンス比較
セキュリティ概要 -- DomPDFに対するセキュリティ改善
APIリファレンス -- TCPDF-Next完全APIドキュメント

DomPDFからの移行 ​

DomPDFアプローチ vs TCPDF-Nextアプローチ ​

APIマッピング ​

基本的な移行サンプル ​

CSSサポート比較 ​

CoreとArtisanの使い分け ​

パフォーマンス比較 ​

移行後の新機能 ​

さらに詳しく ​