各ページに繰り返し表示されるヘッダーとフッターを追加する

概要

ヘッダー（タイトルと説明）とフッターを一度構成すると、レイアウトエンジンは、自動改ページで作成されたページを含む各ページにそれらをレンダリングします。データは最初の addPage() の前に設定します。ヘッダーやフッターをページごとに描画することは決してありません。このレシピは examples/13-header-footer.php に沿っています。

インストール

composer require nextpdf/core:^3

オプションの拡張機能は不要です。Layout concern のヘッダーおよびフッター API は 1.0.0 以降安定しており、8.1–8.4 のバックポートマトリックスで動作します。

概念的な概要

ヘッダーとフッターはページのファーニチャー（付帯要素）です。レイアウトエンジンは、ページをフラッシュするときに、各ページで予約された上下の帯へそれらを描画します。setHeaderData() はコンテンツを記録します。setHeaderFont()、setHeaderMargin()、setFooterFont()、および setFooterMargin() は、タイポグラフィとページ端からの距離を設定します。setPrintHeader(false) と setPrintFooter(false) は、ファーニチャーが不要なドキュメントでその出力をオフにします。

ヘッダーとフッターのジオメトリは、ページ境界を基準に測定されます。ページオブジェクト辞書（ISO 32000-2 §7.7.3.3）は、MediaBox エントリをメディア境界、CropBox エントリをページがクリップされる可視領域として定義しています。セクション 14.11.2 では、これらのページ境界のセマンティクスをさらに詳しく説明しています。設定するヘッダーマージンは、その境界からのオフセットです。ヘッダーとフッターのマークは個別のオブジェクトではありません。各ページの Contents ストリームの一部として、ページごとに出力されます（§7.7.3.3）。

API サーフェス

API サーフェスは PHPDoc から自動生成されます。このレシピでは、次のメソッドを使用します。

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — ヘッダーコンテンツ。
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — ヘッダーとフッターのタイポグラフィ。
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — ページ端からの距離（ミリメートル単位）。
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — ファーニチャー出力の切り替え。

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setHeaderData(title: 'Quarterly Report', description: 'Confidential');
$doc->setHeaderFont('helvetica', 10);
$doc->setFooterFont('helvetica', 8);

$doc->addPage();
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Body text. The header and footer appear on this page '
    . 'and on every page added afterwards, with no per-page code.');
$doc->addPage();
$doc->multiCell(0, 7, 'Page 2 — the furniture repeats automatically.');

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/header-footer.pdf');

コードサンプル — プロダクション

これは、ハーネスに対応した完全なサンプルです。NEXTPDF_COOKBOOK_OUTPUT を尊重し、独自のエントロピーは固定しません。

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Header and Footer');

// Configure the header once, before the first page. The layout engine
// draws it on every page, including auto-break pages.
$doc->setHeaderData(
    title: 'NextPDF Example',
    description: 'Header and Footer Demonstration',
);
$doc->setHeaderFont('helvetica', 10);
$doc->setHeaderMargin(5);

// Configure the footer. The footer band carries the page number.
$doc->setFooterFont('helvetica', 8);
$doc->setFooterMargin(10);

$doc->addPage();
$doc->setFont('helvetica', 'B', 16);
$doc->cell(0, 12, 'Document with Header and Footer', newLine: true);
$doc->ln(5);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'This document has a header with a title and description '
    . 'that repeats on every page. The footer shows the page number.');

$doc->addPage();
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'This is page 2. The header and footer appear without '
    . 'any additional code on each new page.');

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/header-footer.pdf';
$doc->save($out);

echo "Created header-footer.pdf\n";

エッジケースと注意点

ファーニチャーは最初のページの前に設定します。 setHeaderData() を addPage() の後に呼び出しても、それ以前のページは再描画されません。必ず最初の addPage() の前に構成してください。
ヘッダーマージンとコンテンツの上マージン。 ヘッダーマージンは、ヘッダーがページ端からどれだけ離れるかを表し、本文の上マージンとは独立しています。本文の上マージンがヘッダーの帯よりも小さい場合、両者が重なる可能性があるため、十分な余裕を持たせてください。
ファーニチャーはページ単位ではなくドキュメント単位で抑制します。 setPrintHeader(false) はドキュメント全体に適用されます。組み込みのページ単位の切り替えはありません。ファーニチャーのない表紙は、別個のドキュメントにするか、意図的なレイアウト上の選択として扱います。
ロゴのパス。 $logo 引数（setHeaderData() に渡すもの）はローカルファイルパスです。画像ローダーは URL スキームを拒否するため（画像のレシピを参照）、ローカルファイルを渡してください。

パフォーマンス

ヘッダーとフッターのレンダリングはページごとに実行されます。そのコストは本文のサイズではなく、ファーニチャーのコンテンツ（少量のテキストラン）に応じてスケールするため、ページごとのフラッシュに加わるオーバーヘッドはごくわずかです。2000 ms / 64 MB のバジェットは、各ページにファーニチャーを備えた数百ページのドキュメントをカバーします。

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

ヘッダーのタイトルと説明は、ドキュメントテキストとしてレンダリングされます。テナント名など、ユーザーが制御できるデータを含める場合は、本文テキストと同じように長さを制限し、サニタイズしてください。このレシピは解析もネットワークアクセスも行いません。

準拠

記述	仕様	箇条
`MediaBox` ページオブジェクト辞書エントリによる、header/footer ジオメトリの測定基準となるページのメディア境界の定義	ISO 32000-2	§7.7.3.3
`CropBox` ページオブジェクト辞書エントリによる、ページがクリップされる可視領域の定義	ISO 32000-2	§7.7.3.3
各ページの `Contents` ストリームの一部としてのヘッダー/フッターのマーク	ISO 32000-2	§7.7.3.3

再現性プロファイル — 構造的。 トレーラーの /ID と /CreationDate / /ModDate のアトムは、保存のたびに変化します。ハーネスはこれらのアトムを取り除いてから、qpdf で正規化した構造を比較します。このレシピは、NextPDF がどのように構造を生成するかを説明するものであり、ISO 32000-2 への準拠を一律に主張するものではありません。

商用コンテキスト

該当しません。繰り返し表示されるヘッダーとフッターは Core の機能であり、Premium のゲートはありません。