Wiederkehrende Kopf- und Fußzeilen hinzufügen

Auf einen Blick

Konfigurieren Sie Kopfzeile (Titel plus Beschreibung) und Fußzeile einmal. Die Layout-Engine rendert sie auf jeder Seite, auch auf Seiten, die durch automatische Seitenumbrüche entstehen. Legen Sie die Daten vor dem ersten addPage() fest. Sie zeichnen Kopf- oder Fußzeile nie pro Seite. Dieses Recipe folgt examples/13-header-footer.php.

Installation

composer require nextpdf/core:^3

Es ist keine optionale Erweiterung erforderlich. Die API für Kopf- und Fußzeile im Layout-Concern ist seit 1.0.0 stabil und unterstützt die Backport-Matrix 8.1–8.4.

Konzeptioneller Überblick

Kopf- und Fußzeile gehören zur Seitenmöblierung. Die Layout-Engine zeichnet sie beim Flush einer Seite in den reservierten oberen und unteren Bändern jeder Seite. setHeaderData() erfasst den Inhalt. setHeaderFont(), setHeaderMargin(), setFooterFont() und setFooterMargin() legen Typografie und Abstand zur Seitenkante fest. setPrintHeader(false) und setPrintFooter(false) schalten die Möblierung für Dokumente ab, die sie nicht verwenden sollen.

Die Geometrie von Kopf- und Fußzeile wird relativ zur Seitengrenze gemessen. Das Page-Object-Dictionary (ISO 32000-2 §7.7.3.3) definiert den Eintrag MediaBox als Mediengrenze und den Eintrag CropBox als sichtbaren Bereich, auf den die Seite zugeschnitten wird. Abschnitt 14.11.2 beschreibt die Semantik dieser Seitengrenzen im Detail. Der von Ihnen festgelegte Seitenrand der Kopfzeile ist der Versatz zu dieser Grenze. Die Markierungen für Kopf- und Fußzeile sind keine eigenständigen Objekte; sie sind Teil des Contents-Streams jeder Seite und werden pro Seite ausgegeben (§7.7.3.3).

API-Oberfläche

Die API-Oberfläche wird automatisch aus dem PHPDoc generiert. Dieses Recipe verwendet diese Methoden:

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — Inhalt der Kopfzeile.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — Typografie von Kopf- und Fußzeile.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — Abstand zur Seitenkante in Millimetern.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — Möblierung ein- oder ausschalten.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

Dies ist das vollständige, Harness-fertige Beispiel. Es berücksichtigt NEXTPDF_COOKBOOK_OUTPUT und führt keine eigene Entropie ein.

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

Grenzfälle & Stolperfallen

Legen Sie die Möblierung vor der ersten Seite fest. Ein Aufruf von setHeaderData() nach addPage() zeichnet frühere Seiten nicht neu; konfigurieren Sie sie deshalb vor dem ersten addPage().
Seitenrand der Kopfzeile versus oberer Rand des Inhalts. Der Seitenrand der Kopfzeile ist ihr Abstand zur Seitenkante und unabhängig vom oberen Rand des Textkörpers. Beide können sich überlappen, wenn der obere Rand des Textkörpers kleiner ist als das Band der Kopfzeile; lassen Sie also Freiraum.
Unterdrücken Sie die Möblierung pro Dokument, nicht pro Seite. setPrintHeader(false) gilt für das gesamte Dokument. Es gibt keinen eingebauten Schalter pro Seite. Eine Titelseite ohne Möblierung ist ein eigenes Dokument oder eine bewusste Layout-Entscheidung.
Logo-Pfad. Das Argument $logo von setHeaderData() ist ein lokaler Dateipfad. Der Image-Loader weist ein URL-Schema zurück (siehe das Recipe zu Bildern); übergeben Sie also eine lokale Datei.

Performance

Das Rendern von Kopf- und Fußzeile erfolgt pro Seite. Der Aufwand skaliert mit dem Inhalt der Möblierung (einige Text-Runs), nicht mit der Größe des Textkörpers, und verursacht daher beim Flush pro Seite nur vernachlässigbaren Mehraufwand. Das Budget von 2000 ms / 64 MB deckt ein Dokument mit mehreren Hundert Seiten ab, das auf jeder Seite Möblierung verwendet.

Sicherheitshinweise

Titel und Beschreibung der Kopfzeile werden als Dokumenttext gerendert. Enthalten sie benutzergesteuerte Daten, zum Beispiel einen Mandantennamen, begrenzen und bereinigen Sie sie genauso wie den Textkörper. Dieses Recipe führt kein Parsing und keinen Netzwerkzugriff durch.

Konformität

Aussage	Spezifikation	Klausel
`MediaBox` ist der Page-Object-Dictionary-Eintrag, der die Mediengrenze der Seite definiert, relativ zu der die Geometrie von header/footer gemessen wird.	ISO 32000-2	§7.7.3.3
`CropBox` ist der Page-Object-Dictionary-Eintrag mit dem sichtbaren Bereich, auf den die Seite zugeschnitten wird.	ISO 32000-2	§7.7.3.3
Die Markierungen für Kopf- und Fußzeile sind Teil des `Contents`-Streams jeder Seite.	ISO 32000-2	§7.7.3.3

Reproduzierbarkeitsprofil — strukturell. Das /ID im Trailer sowie die Atome /CreationDate / /ModDate variieren pro Speichervorgang. Das Harness entfernt diese Atome und vergleicht anschließend die qpdf-normalisierte Struktur. Dieses Recipe beschreibt, wie NextPDF die Struktur erzeugt; es beansprucht keine pauschale ISO 32000-2-Konformität.

Kommerzieller Kontext

Nicht zutreffend. Wiederkehrende Kopf- und Fußzeilen sind eine Core-Fähigkeit ohne Premium-Gate.