パフォーマンス

TCPDF-Nextは高スループットのドキュメント生成向けに設計されています。このページでは、組み込みの最適化とライブラリを最大限に活用するためのベストプラクティスについて説明します。

サブエンジンの遅延初期化

Document クラスは20以上のサブエンジン（Graphics、Typography、Barcode、Forms、Layersなど）への参照を保持していますが、そのほとんどは遅延初期化されます。最初にアクセスされた時のみ生成されます。

シンプルなテキストのみのPDFでは、SVGパーサー、バーコードエンジン、フォームフィールドマネージャーがインスタンス化されることはありません。これにより、実際に使用する機能に比例したメモリ使用量が保たれます。

フォントサブセッティング

デフォルトでは、TCPDF-Nextはドキュメントで実際に使用されたグリフのみを埋め込みます。FontSubsetter はすべてのテキストコンテンツを分析し、埋め込み前にTrueType/OpenTypeフォントから未使用のグリフを除去します。

これにより、少ない文字セットを使用するドキュメントでは、フォントデータを数メガバイトから数キロバイトに削減できます。

use Yeeefang\TcpdfNext\Core\Document;

// フォントサブセッティングはデフォルトで有効 — 有効化の必要なし
$pdf = Document::create()
    ->addPage()
    ->setFont('DejaVuSans', '', 12)
    ->cell(0, 10, 'Only these glyphs are embedded.');

FlateDecode圧縮

すべてのコンテンツストリームはzlib（FlateDecode）を使用して圧縮されます。これはデフォルトで有効であり、ext-zlib PHP拡張モジュールが必要です。圧縮により、PDFファイルサイズは通常60〜80%削減されます。

ストリーミング出力（PdfWriterChunked）

非常に大きなドキュメントでは、チャンクライターがPDF全体をメモリに保持する代わりに、確定したページデータを段階的にフラッシュします。これは透過的であり、ドキュメントサイズに関係なく同じ save() と output() メソッドが機能します。

use Yeeefang\TcpdfNext\Core\Document;

// 大規模ドキュメントのストリーミング出力
$pdf = Document::create();
$pdf->addPage()->setFont('Helvetica', '', 10);

for ($i = 0; $i < 5000; $i++) {
    $pdf->cell(0, 5, "Row {$i}: data content here", newLine: true);
}

$pdf->save('large-document.pdf');
// フォントサブセッティングとFlateDecode圧縮は自動的に実行されます

クロスリファレンスストリーム

TCPDF-Nextは従来のxrefテーブルの代わりにクロスリファレンスストリーム（PDF 1.5+）を使用します。クロスリファレンスストリーム自体が圧縮されるため、特に多くのオブジェクトを持つドキュメントでファイルサイズが小さくなります。

リニアライゼーション（Fast Web View）

リニアライゼーションはPDFオブジェクトを並べ替え、ファイル全体がダウンロードされる前に最初のページを表示できるようにします。HTTP経由で配信されるすべてのPDFに対してこれを有効にしてください：

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setLinearization(true)
    ->addPage()
    ->cell(0, 10, 'Progressive rendering in the browser')
    ->save('web-optimized.pdf');

Linearizer は、ビューアにオンデマンドでページを取得する方法を伝えるヒントストリームを挿入します。

ページ制限

Document::MAX_PAGES 定数のデフォルトは 10,000 ページです。これは生成中の無限ループに対するセーフガードです。ユースケースでそれ以上が必要な場合は、クラスを拡張してオーバーライドできます。

ベストプラクティス

ページ間でフォントインスタンスを再利用

フォントを一度設定し、ページ間でそのまま引き継ぎましょう。フォントが実際に変更されない限り、ページごとに setFont() を呼び出すことは避けてください：

$pdf = Document::create()
    ->setFont('Helvetica', '', 10);

for ($i = 0; $i < 100; $i++) {
    $pdf->addPage()
        ->cell(0, 5, "Page {$i} content");
}

繰り返しコンテンツにはテンプレート（XObjects）を使用

すべてのページに同じヘッダー、フッター、または透かしがある場合は、テンプレートとして一度作成し、各ページにスタンプしてください。これにより、コンテンツが複製される代わりに、複数回参照される単一のPDFオブジェクトとして保存されます。

圧縮を有効に保つ

圧縮はデフォルトで有効です。デバッグのために生のPDFストリームを検査する必要がない限り、無効にしないでください。

大規模ドキュメントにはストリーミング出力を使用

数百ページを超えるドキュメントでは、ストリーミング出力によりページ数に関係なくメモリ使用量が一定に保たれます。

フォントのサブセット化

フォントサブセッティングはデフォルトで有効です。本番環境では無効にしないでください。フォント全体の埋め込みは、ファイルサイズが数メガバイト増加する可能性があります。

トランザクションスコープを最小化

トランザクションはドキュメントの完全なスナップショットを保存します。メモリ使用量の倍増を避けるため、短期間で完了させましょう。詳細はトランザクションを参照してください。

まとめ

機能	デフォルト	効果
フォントサブセッティング	オン	フォントサイズの削減（KBレベル vs MBレベル）
FlateDecode圧縮	オン	ストリームの60〜80%削減
クロスリファレンスストリーム	オン	xrefデータの削減
遅延初期化	オン	使用機能に比例したメモリ
ストリーミング出力	自動	大規模ドキュメントで一定のメモリ
リニアライゼーション	オフ	Web配信PDFで有効化