Kopfzeilen, Fußzeilen und mehrseitige Dokumente

Eine Seite reicht selten aus. In diesem Tutorial schreiben Sie ein Dokument, das von selbst auf drei Seiten anwächst. Außerdem versehen Sie jede Seite mit einer wiederkehrenden Kopfzeile und einer Fußzeile, die die Seitenzahl anzeigt.

Was Sie erstellen

Sie schreiben ein einziges Skript, 01-multipage.php. Es erzeugt ein dreiseitiges Reisetagebuch als PDF-Datei (Portable Document Format):

• Die Tagebucheinträge fließen automatisch von Seite zu Seite. Sie geben nie an, wo eine Seite endet; die Engine entscheidet das.
• Eine Kopfzeile ist ein Streifen am oberen Rand einer Seite, der sich auf jeder Seite wiederholt. Ihre zeigt den Dokumenttitel.
• Eine Fußzeile ist der entsprechende Streifen am unteren Rand. Ihre zeigt die Seitenzahl als 1 / 3, 2 / 3 und 3 / 3.

Alles läuft allein mit dem Paket nextpdf/core: keine Schriftdateien, keine zusätzlichen Erweiterungen und kein Netzwerk.

Schritt 1: Das dreiseitige Tagebuch erstellen

Zwei Konzepte erledigen die gesamte Arbeit in diesem Skript.

Das erste ist der automatische Seitenumbruch. Während die Engine Text schreibt, verfolgt sie einen Cursor: die Stelle auf der Seite, an der die nächste Zeile landet. setAutoPageBreak(true, margin: 25) weist die Engine an, diesen Cursor zu beobachten. Sobald er bis auf 25 Punkte (etwa ein Drittel Zoll) an den unteren Rand herankommt, schließt die Engine die Seite und beginnt eine neue.

Das zweite ist das Seitenbeiwerk: die Kopf- und die Fußzeile. Sie beschreiben es einmal, vor der ersten Seite. setHeaderData() hält den Titel und eine kurze Beschreibung für den oberen Streifen fest. Die Aufrufe für Schrift und Rand wählen die Beschriftung und den Abstand zum Seitenrand. Die Engine zeichnet dieses Beiwerk dann auf jede Seite, die sie erstellt – auch auf die Seiten, die sie selbst hinzufügt.

Erstellen Sie 01-multipage.php in Ihrem Projektordner:

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

Führen Sie es mit php 01-multipage.php aus. Das Skript gibt eine Zeile aus:

Wrote out/travel-journal.pdf with 3 pages

Öffnen Sie out/travel-journal.pdf und scrollen Sie hindurch. Der Titelstreifen sitzt am oberen Rand aller drei Seiten, und die Seitenzahlen zählen unten rechts hoch.

Was gerade geschah

Die Schreibschleife erwähnt Seiten mit keinem Wort. Sie schreibt jede Tagesüberschrift mit cell(), das eine Zeile in ein unsichtbares Kästchen setzt. Die Einträge schreibt sie mit multiCell(), das langen Text auf so viele Zeilen umbricht, wie es braucht. Sechsunddreißig Einträge passen nicht auf eine Seite, deshalb löst der automatische Seitenumbruch zweimal aus. So wird das Tagebuch zu genau drei Seiten.

Die Kopf- und die Fußzeile wurden vor dem ersten Aufruf von addPage() konfiguriert. Diese Reihenfolge ist wichtig: Eine bereits gezeichnete Seite wird nachträglich nicht mehr aktualisiert. Konfigurieren Sie das Beiwerk zuerst, dann wird jede Seite einheitlich.

Sie haben die Seitenzahl nie selbst gezeichnet. Die Fußzeile gibt sie standardmäßig aus; Sie haben lediglich ihre Schrift und ihren Abstand zum Seitenrand gewählt. Während die Engine die Seiten schreibt, kann sie die endgültige Anzahl noch nicht kennen. Deshalb lässt sie in jeder Fußzeile einen Platzhalter und trägt die tatsächliche Gesamtzahl beim Speichern ein.

Zwei kleine Details runden das Skript ab. @mkdir erstellt den Ordner out, und das Zeichen @ sorgt dafür, dass PHP still bleibt, wenn der Ordner bereits existiert. getNumPages() fragt die Engine, wie viele Seiten das Layout erzeugt hat, damit die abschließende Meldung die tatsächliche Anzahl nennen kann.

Falls etwas schiefgegangen ist

• Ein Fehler „failed to open stream“ in der require-Zeile bedeutet, dass das Skript vendor/autoload.php nicht finden konnte. Führen Sie es in dem Projektordner aus, der vendor/ enthält.
• Alles steht auf einer einzigen Seite und das Ende des Textes ist abgeschnitten? Dann sind die automatischen Seitenumbrüche ausgeschaltet. Behalten Sie die Zeile setAutoPageBreak(true, margin: 25) bei und halten Sie sie oberhalb der Schreibschleife.
• Eine falsch geschriebene Schriftfamilie löst eine Ausnahme aus, die die nicht gefundene Schrift benennt. Prüfen Sie die Schreibweise von helvetica und lesen Sie bei tiefergehenden Schriftproblemen Schriften und Tagging.
• Für alles andere ordnet der Fehlerbehebungs-Hub Symptome den Ursachen zu, und die Fehlerreferenz erläutert die allgemeinen Ausnahmen der Engine und wie Sie jede davon beheben.

Weiter

Ihre Dokumente können jetzt auf beliebige Länge anwachsen und wirken dennoch fertig. Im nächsten Tutorial schreiben Sie Ihren Inhalt in HTML (Hypertext Markup Language) und lassen die Engine daraus Seiten erzeugen.

Wenn Sie feinere Kontrolle über die heutigen Themen möchten, gehen zwei Rezepte tiefer:

• Ein mehrseitiges Dokument erstellen behandelt den Seitenumbruch im Detail, einschließlich seiner Grenzfälle.
• Wiederkehrende Seitenkopf- und -fußzeilen hinzufügen führt durch jede Kopf- und Fußzeileneinstellung, einschließlich des Ausschaltens.