Añadir encabezados y pies de página repetidos

De un vistazo

Configura una sola vez el encabezado (un título y una descripción) y el pie de página, y el motor de maquetación los renderiza en cada página, incluidas las creadas por saltos de página automáticos. Define estos datos antes del primer addPage(). No es necesario dibujar el encabezado ni el pie de página en cada página. Esta recipe se basa en examples/13-header-footer.php.

Instalación

composer require nextpdf/core:^3

No se requiere ninguna extensión opcional. La API de encabezado y pie de página del concern Layout es estable desde la versión 1.0.0 y funciona sobre la matriz de backport 8.1–8.4.

Panorama conceptual

Un encabezado y un pie de página son elementos fijos de la página. El motor de maquetación los dibuja en las bandas superior e inferior reservadas de cada página durante su vaciado. setHeaderData() registra el contenido. setHeaderFont(), setHeaderMargin(), setFooterFont() y setFooterMargin() establecen la tipografía y la distancia respecto al borde de la página. setPrintHeader(false) y setPrintFooter(false) desactivan estos elementos en los documentos que no los necesitan.

La geometría del encabezado y del pie de página se mide con respecto al límite de la página. El diccionario del objeto de página (ISO 32000-2 §7.7.3.3) define la entrada MediaBox como el límite del medio y la entrada CropBox como la región visible a la que se recorta la página. La sección 14.11.2 detalla la semántica de esos límites de página. El margen de encabezado que se define es el desplazamiento respecto a ese límite. Las marcas del encabezado y del pie de página no son un objeto aparte; forman parte del flujo Contents de cada página y se emiten página por página (§7.7.3.3).

Superficie de la API

La superficie de la API se genera automáticamente a partir de PHPDoc. Esta recipe utiliza estos métodos:

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — contenido del encabezado.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — tipografía del encabezado y del pie de página.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — distancia con respecto al borde de la página, en milímetros.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — activan o desactivan estos elementos.

Ejemplo de código — Inicio 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');

Ejemplo de código — Producción

Este es el ejemplo completo, preparado para el harness. Respeta NEXTPDF_COOKBOOK_OUTPUT y no fija ninguna entropía propia.

<?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 límite y trampas

Configurar estos elementos antes de la primera página. Una llamada a setHeaderData() después de addPage() no vuelve a dibujar las páginas anteriores, así que debe configurarse antes del primer addPage().
Margen del encabezado frente al margen superior del contenido. El margen del encabezado es la distancia del encabezado respecto al borde de la página y es independiente del margen superior del cuerpo. Ambos pueden solaparse si el margen superior del cuerpo es menor que la banda del encabezado, así que conviene dejar espacio suficiente.
Suprimir estos elementos por documento, no por página. setPrintHeader(false) se aplica a todo el documento. No existe un interruptor integrado por página. Una portada sin estos elementos es un documento aparte o una decisión de maquetación deliberada.
Ruta del logotipo. El argumento $logo de setHeaderData() es la ruta de un archivo local. El cargador de imágenes rechaza los esquemas de URL (consulta la recipe de imágenes), así que debe pasarse un archivo local.

Rendimiento

El renderizado del encabezado y del pie de página se ejecuta por página. Su costo escala con el contenido de estos elementos (unos pocos fragmentos de texto), no con el tamaño del cuerpo, así que añade una sobrecarga insignificante al vaciado de cada página. El presupuesto de 2000 ms / 64 MB cubre un documento de varios cientos de páginas con estos elementos en cada página.

Notas de seguridad

El título y la descripción del encabezado se renderizan como texto del documento. Si contienen datos controlados por el usuario, por ejemplo, un nombre de inquilino, hay que limitar su longitud y sanitizarlos del mismo modo que se trata el texto del cuerpo. Esta recipe no realiza ningún análisis ni accede a la red.

Conformidad

Declaración	Especificación	Cláusula
La entrada `MediaBox` del diccionario del objeto de página define el límite del medio de la página respecto al cual se mide la geometría del encabezado y del pie de página.	ISO 32000-2	§7.7.3.3
La entrada `CropBox` del diccionario del objeto de página es la región visible a la que se recorta la página.	ISO 32000-2	§7.7.3.3
Las marcas del encabezado y del pie de página forman parte del flujo `Contents` de cada página.	ISO 32000-2	§7.7.3.3

Perfil de reproducibilidad — estructural. El /ID del tráiler y los átomos /CreationDate / /ModDate varían en cada guardado. El harness elimina esos átomos y luego compara la estructura normalizada con qpdf. Esta recipe describe cómo NextPDF produce la estructura; no afirma la conformidad con ISO 32000-2 como una declaración general.

Contexto comercial

No aplica. Los encabezados y pies de página repetidos son una capacidad del núcleo, sin restricción por nivel Premium.