Core / HasLayout トレイト

概要

HasLayout は、ページの装飾要素を扱う concern トレイトです。Document ファサードで、ヘッダー、フッター、段組みレイアウト、ブックレットモードを構成します。

インストール

composer require nextpdf/core:^3

概念の概要

trait HasLayout（src/Core/Concerns/HasLayout.php、1.2.0 以降）は Document に組み込まれます。処理は、3 つのエンジンである HeaderFooter、ColumnLayout、BookletLayout に委譲されます。

繰り返し表示されるヘッダーとフッターを追加するには、次の手順を実行します。

setHeaderData(title, description, logo, logoWidth) を呼び出します。
setHeaderFont(family, size) と setHeaderMargin(margin) を呼び出します。
setFooterFont(family, size) と setFooterMargin(margin) を呼び出します。
ページを追加します。ヘッダーは addPage() ごとにレンダリングされます。フッターは、ページがフラッシュされるたびにレンダリングされます。

setPrintHeader(bool) と setPrintFooter(bool) は、自動レンダリングの有効・無効を切り替えます。完全に制御したい場合は、setHeaderCallback(Closure) と setFooterCallback(Closure) を使用すると、デフォルトのレンダリングを独自のクロージャーで置き換えられます。

段組みレイアウトでは setEqualColumns(int $count, float $gap = 5) を使用します。このトレイトは、現在のページサイズとマージンから利用可能な幅を算出し、それを均等な段に分割します。selectColumn(int $index) は、カーソルを選択した段の開始 X 位置に移動します。resetColumns() は、レイアウトを単一段の全幅モードに戻します。

setBooklet(bool $enabled, float $innerMargin = 0, float $outerMargin = 0) は、両面印刷向けにブックレットのページ並べ替えを有効にします。BookletLayout エンジンは、初めて使用されたときに作成されます。それまでは null のままです。これにより、基本フットプリントを小さく保てます。

ヘッダーとフッターのコンテンツは、コンテンツストリームの演算子としてページに反映されます。エンジンは、各オペランドをその演算子の直前に出力します（ISO 32000-2:2020 §7.8.2）。タグ付き PDF モードでは、ヘッダーは抑制されます。ヘッダーのコンテンツは構造ツリーの一部ではなく、タグなしコンテンツ違反を引き起こすためです。

API サーフェス

シンボル	種別	安定性	導入バージョン
`setHeaderData(string, string, string, float): static`	メソッド	安定	1.2.0
`setHeaderFont(string, float): static`	メソッド	安定	1.2.0
`setHeaderMargin(float): static`	メソッド	安定	1.2.0
`setFooterFont(string, float): static`	メソッド	安定	1.2.0
`setFooterMargin(float): static`	メソッド	安定	1.2.0
`setPrintHeader(bool): static` / `setPrintFooter(bool): static`	メソッド	安定	1.2.0
`setHeaderCallback(Closure): static` / `setFooterCallback(Closure): static`	メソッド	安定	1.2.0
`setEqualColumns(int, float): static`	メソッド	安定	1.2.0
`selectColumn(int): static` / `resetColumns(): static`	メソッド	安定	1.2.0
`setBooklet(bool, float, float): static`	メソッド	安定	1.2.0

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

$doc->setHeaderData(
    title: 'NextPDF Example',
    description: 'Header and Footer Demonstration',
);
$doc->setHeaderFont('helvetica', 10);
$doc->setHeaderMargin(5);
$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->save(__DIR__ . '/output/13-header-footer.pdf');

ソース：examples/13-header-footer.php。

コードサンプル — 本番運用

フッターコールバックがページ番号のテキストを管理するため、その書式はアプリケーションの制御下に置かれます。

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Two-Column Report');

$doc->setFooterCallback(static function (Document $d): void {
    $d->setFont('helvetica', '', 8);
    $d->text(180.0, 285.0, 'Page ' . $d->getPage() + 1);
});

$doc->addPage();
$doc->setEqualColumns(2, gap: 8);
$doc->selectColumn(0);
$doc->setFont('helvetica', '', 10);
$doc->multiCell(0, 6, 'Left column flows here.');
$doc->selectColumn(1);
$doc->multiCell(0, 6, 'Right column flows here.');

$doc->save(__DIR__ . '/output/two-column-report.pdf');

ソース：examples/13-header-footer.php に基づくパターン。

エッジケースと注意点

ヘッダーは addPage() ごとにレンダリングされ、フッターはページがフラッシュされるときにレンダリングされます。個別に「今すぐレンダリングする」ための呼び出しはありません。
タグ付き PDF モードでは、タグなしコンテンツ違反を避けるため、自動ヘッダーは抑制されます。アクセシブルなドキュメントには、構造を考慮したレイアウトを使用してください。
setEqualColumns() は、呼び出し時のページサイズとマージンを読み取ります。サイズがデフォルトと異なる場合は、ページを作成してから呼び出してください。
selectColumn() は X を段の開始位置に設定しますが、Y はリセットしません。段を切り替えるときは、垂直位置を自分で管理してください。
setBooklet() は両面出力向けにページを並べ替えますが、movePage() に渡すページインデックスは引き続き論理的な順序を指します。

パフォーマンス

ヘッダーとフッターのレンダリングは、O(装飾要素のコンテンツ) でアクティブなページバッファーに演算子を追加します。段の計算は、呼び出しごとに O(1) です。BookletLayout は、最初の setBooklet() 呼び出し時に遅延作成されます。予算：標準的なクイックスタートで 1500 ms / 64 MB。

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

このトレイトは、呼び出し元が提供する文字列とロゴのパスを受け取ります。ロゴのパスは画像エンジンを経由し、画像エンジンがファイルを検証します。ヘッダーまたはフッターのコールバックは、呼び出し元のコードを実行します。コールバックが読み取る外部データは、ドキュメントの他の部分と同様に注意して扱ってください。

準拠

主張	出典	条項	リファレンス ID
ヘッダーとフッターのコンテンツは、コンテンツストリームの演算子として出力される（オペランドは演算子の直前に置かれる）	ISO 32000-2:2020	§7.8.2

条項は要約したものであり、規範的な本文は転載していません。