Добавление повторяющихся колонтитулов

Краткий обзор

Настройте верхний колонтитул (заголовок и описание) и нижний колонтитул один раз. Механизм компоновки будет выводить их на каждой странице, включая страницы, созданные автоматическими разрывами страниц. Задайте данные до первого вызова addPage(). Вам не нужно отрисовывать верхний или нижний колонтитул на каждой странице. Этот рецепт основан на examples/13-header-footer.php.

Установка

composer require nextpdf/core:^3

Дополнительное расширение не требуется. API верхнего и нижнего колонтитулов в Layout стабилен начиная с версии 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 мс / 64 МБ хватает для документа на несколько сотен страниц со служебными элементами на каждой странице.

Замечания по безопасности

Заголовок и описание верхнего колонтитула отображаются как текст документа. Если они содержат данные, контролируемые пользователем, например имя арендатора, ограничьте их длину и очищайте так же, как текст основного содержимого. Этот рецепт не выполняет парсинг и не обращается к сети.

Соответствие

Утверждение	Спецификация	Пункт
`MediaBox` — запись словаря объекта страницы, определяющая границу носителя страницы, от которой отсчитывается геометрия header/footer.	ISO 32000-2	§7.7.3.3
`CropBox` — запись словаря объекта страницы, представляющая видимую область, по которой обрезается страница.	ISO 32000-2	§7.7.3.3
Маркеры header/footer входят в поток `Contents` каждой страницы.	ISO 32000-2	§7.7.3.3

Профиль воспроизводимости — структурный. Атомы /ID трейлера и /CreationDate / /ModDate меняются при каждом сохранении. Тестовый стенд удаляет эти атомы, а затем сравнивает структуру, нормализованную с помощью qpdf. Этот рецепт описывает, как NextPDF формирует эту структуру. Это не является исчерпывающим заявлением о соответствии ISO 32000-2.

Коммерческий контекст

Неприменимо. Повторяющиеся колонтитулы — это функция Core без ограничения Premium.