Herhalende kop- en voetteksten toevoegen

In één oogopslag

Configureer één keer een koptekst (met titel en beschrijving) en een voettekst. De lay-out-engine geeft ze op elke pagina weer, ook op pagina’s die door automatische pagina-einden ontstaan. Stel de gegevens in vóór de eerste addPage(). Je tekent de koptekst of voettekst dus niet per pagina. Dit recipe volgt examples/13-header-footer.php.

Installeren

composer require nextpdf/core:^3

Er is geen optionele extensie nodig. De application programming interface (API) voor koptekst en voettekst in het Layout-concern is stabiel sinds 1.0.0. Deze wordt ondersteund binnen de 8.1–8.4-backportmatrix.

Conceptueel overzicht

Een koptekst en een voettekst zijn vaste pagina-elementen. De lay-out-engine tekent ze in de gereserveerde boven- en onderbanden van elke pagina wanneer die de pagina wegschrijft. setHeaderData() legt de inhoud vast. setHeaderFont(), setHeaderMargin(), setFooterFont() en setFooterMargin() stellen de typografie en de afstand tot de paginarand in. setPrintHeader(false) en setPrintFooter(false) schakelen de vaste elementen uit voor documenten die ze niet nodig hebben.

De geometrie van de koptekst en de voettekst wordt gemeten ten opzichte van de paginagrens. De page-object-dictionary (ISO 32000-2 §7.7.3.3) definieert de vermelding MediaBox als de mediumgrens en de vermelding CropBox als het zichtbare gebied waartoe de pagina wordt bijgesneden. Sectie 14.11.2 definieert de semantiek van die paginagrenzen. De koptekstmarge die je instelt, is de verschuiving ten opzichte van die grens. Koptekst- en voettekstmarkeringen zijn geen afzonderlijke objecten; ze maken deel uit van de Contents-stream van elke pagina en worden per pagina uitgevoerd (§7.7.3.3).

API-oppervlak

Het API-oppervlak wordt gegenereerd op basis van PHPDoc. In dit recipe worden de volgende methoden gebruikt:

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — stelt de inhoud van de koptekst in.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — stelt de typografie voor de koptekst en voettekst in.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — stelt de afstand tot de paginarand in, in millimeter.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — schakelt de vaste elementen in of uit.

Codevoorbeeld — Snel aan de slag

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

Codevoorbeeld — Productie

Dit volledige voorbeeld is geschikt voor de harness, houdt rekening met NEXTPDF_COOKBOOK_OUTPUT en legt geen eigen entropie vast.

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

Randgevallen en valkuilen

Stel de vaste elementen in vóór de eerste pagina. Het aanroepen van setHeaderData() na addPage() tekent eerdere pagina’s niet opnieuw; configureer de vaste elementen daarom vóór de eerste addPage().
Koptekstmarge versus bovenmarge van de inhoud. De koptekstmarge is de afstand van de koptekst tot de paginarand. Deze staat los van de bovenmarge van de hoofdtekst. Ze kunnen elkaar overlappen als de bovenmarge van de hoofdtekst kleiner is dan de koptekstband; laat dus voldoende ruimte vrij.
Onderdruk vaste elementen per document, niet per pagina. setPrintHeader(false) is van toepassing op het hele document. Er is geen ingebouwde schakelaar per pagina. Gebruik voor een voorblad zonder vaste elementen een afzonderlijk document of maak een bewuste lay-out-keuze.
Logopad. Het argument $logo van setHeaderData() is een lokaal bestandspad. De afbeeldingslader weigert een URL-schema (zie het recipe over afbeeldingen), dus gebruik een lokaal bestand.

Prestaties

Het renderen van de koptekst en voettekst gebeurt per pagina. De kosten daarvan schalen mee met de inhoud van de vaste elementen (enkele tekstreeksen), niet met de omvang van de hoofdtekst. Het voegt verwaarloosbare overhead toe aan elke pagina-flush. Het budget van 2000 ms / 64 MB dekt een document van enkele honderden pagina’s met vaste elementen op elke pagina.

Beveiligingsopmerkingen

De titel en beschrijving van de koptekst worden als documenttekst weergegeven. Als ze door de gebruiker beheerde gegevens bevatten, zoals een tenantnaam, beperk dan de lengte en saneer ze op dezelfde manier als je hoofdtekst behandelt. Dit recipe voert geen parsing uit en gebruikt geen netwerktoegang.

Conformiteit

Bewering	Specificatie	Clausule
De `MediaBox`-vermelding in de page-object-dictionary definieert de mediumgrens van de pagina waartegen de geometrie van de header/footer wordt gemeten.	ISO 32000-2	§7.7.3.3
De `CropBox`-vermelding in de page-object-dictionary is het zichtbare gebied waartoe de pagina wordt bijgesneden.	ISO 32000-2	§7.7.3.3
Header/footer-markeringen maken deel uit van de `Contents`-stream van elke pagina.	ISO 32000-2	§7.7.3.3

Reproduceerbaarheidsprofiel — structureel. De trailer-/ID en de atomen /CreationDate / /ModDate variëren per keer dat je opslaat. De harness verwijdert die atomen en vergelijkt vervolgens de door qpdf genormaliseerde structuur. Dit recipe beschrijft hoe NextPDF de structuur produceert. Het doet geen algemene bewering over ISO 32000-2-conformiteit.

Commerciële context

Niet van toepassing. Herhalende kopteksten en voetteksten zijn Core-functionaliteit, waarvoor geen Premium-drempel geldt.