Adicione cabeçalhos e rodapés repetidos às páginas

Visão geral

Configure um cabeçalho (com título e descrição) e um rodapé uma única vez. O mecanismo de layout os renderiza em todas as páginas, inclusive nas páginas criadas por quebras de página automáticas. Configure os dados antes do primeiro addPage(). Você não precisa desenhar o cabeçalho nem o rodapé em cada página. Esta receita acompanha examples/13-header-footer.php.

Instalação

composer require nextpdf/core:^3

Nenhuma extensão opcional é necessária. A API de cabeçalho e rodapé do concern Layout é estável desde a versão 1.0.0. Ela funciona na matriz de backport 8.1 - 8.4.

Visão conceitual

O cabeçalho e o rodapé são elementos fixos de página. O mecanismo de layout os desenha nas faixas superior e inferior reservadas de cada página durante a descarga da página. setHeaderData() registra o conteúdo. setHeaderFont(), setHeaderMargin(), setFooterFont() e setFooterMargin() definem a tipografia e a distância em relação à borda da página. setPrintHeader(false) e setPrintFooter(false) desativam esses elementos fixos para documentos que não precisam deles.

A geometria do cabeçalho e do rodapé é medida em relação ao limite da página. O dicionário do objeto de página (ISO 32000-2 §7.7.3.3) define a entrada MediaBox como o limite da mídia e a entrada CropBox como a região visível à qual a página é recortada. A seção 14.11.2 define a semântica desses limites de página. A margem de cabeçalho que você define é o deslocamento em relação a esse limite. As marcas de cabeçalho e rodapé não são objetos separados; elas fazem parte do stream Contents de cada página e são emitidas página a página (§7.7.3.3).

Superfície da API

A superfície da API é gerada a partir do PHPDoc. Esta receita usa os seguintes métodos:

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — define o conteúdo do cabeçalho.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — define a tipografia do cabeçalho e do rodapé.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — define a distância em relação à borda da página, em milímetros.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — ativa ou desativa esses elementos fixos.

Exemplo de código — Início rápido

<?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');

Exemplo de código — Produção

Este exemplo completo, pronto para o harness, respeita NEXTPDF_COOKBOOK_OUTPUT e não fixa sua própria entropia.

<?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";

Casos extremos e pegadinhas

Defina os elementos fixos antes da primeira página. Chamar setHeaderData() depois de addPage() não redesenha páginas anteriores; portanto, configure-o antes do primeiro addPage().
Margem do cabeçalho versus margem superior do conteúdo. A margem do cabeçalho é a distância do cabeçalho em relação à borda da página. Ela é independente da margem superior do corpo. As duas podem se sobrepor se a margem superior do corpo for menor que a faixa do cabeçalho; portanto, deixe uma folga.
Desative os elementos fixos por documento, não por página. setPrintHeader(false) aplica-se ao documento inteiro. Não há um controle integrado de ativação por página. Para criar uma capa sem esses elementos fixos, use um documento separado ou faça uma escolha de layout deliberada.
Caminho do logotipo. O argumento $logo de setHeaderData() é um caminho de arquivo local. O carregador de imagens rejeita um esquema de URL (consulte a receita de imagens), portanto use um arquivo local.

Desempenho

A renderização de cabeçalho e rodapé é executada por página. O custo varia de acordo com o conteúdo desses elementos fixos (algumas sequências de texto), não com o tamanho do corpo. Isso adiciona uma sobrecarga insignificante a cada descarga de página. O orçamento de 2000 ms / 64 MB cobre um documento de várias centenas de páginas com esses elementos fixos em todas as páginas.

Notas de segurança

O título e a descrição do cabeçalho são renderizados como texto do documento. Se eles incluírem dados controlados pelo usuário, como o nome de um tenant, limite o comprimento e faça a sanitização deles da mesma forma que você trata o texto do corpo. Esta receita não realiza análise sintática nem acesso à rede.

Conformidade

Declaração	Especificação	Cláusula
`MediaBox` é a entrada do dicionário do objeto de página que define o limite da mídia da página em relação ao qual a geometria de header/footer é medida.	ISO 32000-2	§7.7.3.3
`CropBox` é a entrada do dicionário do objeto de página que define a região visível à qual a página é recortada.	ISO 32000-2	§7.7.3.3
As marcas de header/footer fazem parte do stream `Contents` de cada página.	ISO 32000-2	§7.7.3.3

Perfil de reprodutibilidade — estrutural. O /ID do trailer e os átomos /CreationDate / /ModDate variam em cada salvamento. O harness remove esses átomos e, em seguida, compara a estrutura normalizada por qpdf. Esta receita descreve como o NextPDF produz a estrutura. Ela não afirma conformidade com a ISO 32000-2 como uma alegação genérica.

Contexto comercial

Não se aplica. Cabeçalhos e rodapés repetidos são um recurso do Core, sem barreira Premium.