Encabezados, pies de página y documentos de varias páginas

Una sola página rara vez es suficiente. En este tutorial se escribe un documento que crece hasta tres páginas por sí solo. Además, se añade a cada página un encabezado que se repite y un pie de página que muestra el número de página.

Qué se va a construir

Se escribe un único script, 01-multipage.php. Produce un diario de viaje de tres páginas en un archivo PDF (Portable Document Format):

Las entradas del diario fluyen de una página a otra automáticamente. Nunca se indica dónde termina una página; lo decide el motor.
Un encabezado es una franja en la parte superior de la página que se repite en todas las páginas. El suyo muestra el título del documento.
Un pie de página es la franja equivalente en la parte inferior. El suyo muestra el número de página como 1 / 3, 2 / 3 y 3 / 3.

Todo funciona únicamente con el paquete nextpdf/core: sin archivos de fuentes, sin extensiones adicionales y sin red.

Paso 1: construir el diario de tres páginas

Dos ideas hacen todo el trabajo en este script.

La primera es el salto de página automático. A medida que el motor escribe texto, mantiene un cursor: el punto de la página donde caerá la siguiente línea. setAutoPageBreak(true, margin: 25) indica al motor que vigile ese cursor. Cuando se acerca a 25 puntos (aproximadamente un tercio de pulgada) del borde inferior, el motor cierra la página y comienza una nueva.

La segunda son los elementos fijos de la página: el encabezado y el pie de página. Se describen una sola vez, antes de la primera página. setHeaderData() registra el título y una breve descripción para la franja superior. Las llamadas de fuente y de margen eligen la tipografía y la distancia desde el borde de la página. Después, el motor dibuja estos elementos fijos en cada página que crea, incluidas las páginas que añade por sí mismo.

Crear 01-multipage.php en la carpeta de su proyecto:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// Make sure the output folder exists next to this script.
@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('NextPDF Travel Journal');

// Configure the header and footer BEFORE the first page.
// The engine repeats them on every page for you.
$document->setHeaderData(title: 'NextPDF Travel Journal', description: 'A multi-page tutorial document');
$document->setHeaderFont('helvetica', 10);
$document->setHeaderMargin(5);
$document->setFooterFont('helvetica', 8);
$document->setFooterMargin(10);

// Turn on automatic page breaks. When the text cursor gets within
// 25 points of the bottom edge, the engine starts a new page.
$document->setAutoPageBreak(true, margin: 25);

$document->addPage();

$document->setFont('helvetica', 'B', 18);
$document->cell(0, 12, 'Travel journal: three days on the coast', newLine: true);
$document->ln(5);

$days = [
    1 => 'We followed the shoreline north and counted seventeen lighthouses.',
    2 => 'Rain moved in before noon, so we sketched the harbor from a cafe window.',
    3 => 'On the last morning the fog lifted and the whole bay turned silver.',
];

foreach ($days as $day => $highlight) {
    $document->setFont('helvetica', 'B', 14);
    $document->cell(0, 10, "Day {$day}", newLine: true);

    $document->setFont('helvetica', '', 11);
    for ($entry = 1; $entry <= 12; $entry++) {
        $text = "Entry {$entry} of day {$day}. {$highlight} "
            . 'The trail hugged the cliffs for most of the afternoon, and every '
            . 'turn opened another view of the water. We stopped often to take '
            . 'notes, compare maps, and argue happily about where to eat dinner. '
            . 'By the time we reached the guesthouse, our boots were soaked and '
            . 'our notebooks were full.';
        $document->multiCell(0, 7, $text);
        $document->ln(3);
    }
    $document->ln(5);
}

// Ask the engine how many pages the layout produced, then save.
$pages = $document->getNumPages();
$document->save(__DIR__ . '/out/travel-journal.pdf');

echo "Wrote out/travel-journal.pdf with {$pages} pages\n";

Ejecutarlo con php 01-multipage.php. El script imprime una línea:

Wrote out/travel-journal.pdf with 3 pages

Abrir out/travel-journal.pdf y desplazarse por él. La franja del título se sitúa en la parte superior de las tres páginas y los números de página aumentan en la esquina inferior derecha.

Qué acaba de ocurrir

El bucle de escritura nunca menciona páginas. Escribe cada encabezado de día con cell(), que coloca una línea en una caja invisible. Escribe las entradas con multiCell(), que ajusta el texto largo en tantas líneas como haga falta. Treinta y seis entradas no caben en una sola página, así que el salto de página automático se activa dos veces. Así es como el diario acaba teniendo exactamente tres páginas.

El encabezado y el pie de página se configuraron antes de la primera llamada a addPage(). Ese orden importa: una página que ya se ha dibujado no se actualiza después. Al configurar primero los elementos fijos, todas las páginas quedan coherentes.

En ningún momento se dibujó el número de página. El pie de página lo imprime de forma predeterminada; solo se eligió su fuente y su distancia desde el borde de la página. Mientras el motor escribe las páginas, todavía no puede conocer el recuento final. Por eso deja un marcador de posición en cada pie de página y rellena el total real al guardar.

Dos pequeños detalles rematan el script. @mkdir crea la carpeta out, y el signo @ mantiene a PHP en silencio cuando la carpeta ya existe. getNumPages() pregunta al motor cuántas páginas produjo el diseño, de modo que el mensaje final pueda informar del recuento real.

Si algo salió mal

Un error «failed to open stream» en la línea require significa que el script no pudo encontrar vendor/autoload.php. Ejecutarlo dentro de la carpeta del proyecto que contiene vendor/.
¿Todo queda en una sola página y el final del texto aparece cortado? Entonces los saltos de página automáticos están desactivados. Mantener la línea setAutoPageBreak(true, margin: 25) y situarla por encima del bucle de escritura.
Una familia de fuentes mal escrita lanza una excepción que indica el nombre de la fuente que no pudo encontrar. Comprobar la ortografía de helvetica y consultar Fuentes y etiquetado para problemas de fuentes más complejos.
Para cualquier otra cosa, el centro de resolución de problemas relaciona los síntomas con sus causas, y la referencia de errores explica las excepciones generales del motor y cómo recuperarse de cada una.

Sus documentos ya pueden crecer hasta cualquier longitud y seguir teniendo un aspecto acabado. En el siguiente tutorial se escribe el contenido en HTML (Hypertext Markup Language) y se deja que el motor lo convierta en páginas.

Cuando se desee un control más preciso sobre los temas de hoy, dos recetas profundizan más:

Crear un documento de varias páginas trata en detalle el salto de páginas, incluidos sus casos límite.
Añadir encabezados y pies de página que se repiten recorre todos los ajustes de encabezado y pie de página, incluida su desactivación.

Encabezados, pies de página y documentos de varias páginas

Qué se va a construir

Paso 1: construir el diario de tres páginas

Qué acaba de ocurrir

Si algo salió mal

Siguiente