Ajouter des en-têtes et pieds de page répétés

En un coup d’œil

Configure une seule fois un en-tête (un titre et une description) ainsi qu’un pied de page ; le moteur de mise en page les restitue ensuite sur chaque page, y compris celles créées par les sauts de page automatiques. Définis ces données avant le premier addPage(). Tu ne dessines jamais l’en-tête ni le pied de page page par page. Ce recipe reprend examples/13-header-footer.php.

Installation

composer require nextpdf/core:^3

Aucune extension optionnelle n’est requise. L’API d’en-tête et de pied de page du module Layout est stable depuis la version 1.0.0 et fonctionne avec la matrice de backport 8.1–8.4.

Vue d’ensemble conceptuelle

Un en-tête et un pied de page forment l’habillage de la page. Le moteur de mise en page les dessine dans les bandes supérieure et inférieure réservées de chaque page, lors du vidage de la page. setHeaderData() enregistre le contenu. setHeaderFont(), setHeaderMargin(), setFooterFont() et setFooterMargin() définissent la typographie et la distance par rapport au bord de la page. setPrintHeader(false) et setPrintFooter(false) désactivent l’habillage pour les documents qui n’en ont pas besoin.

La géométrie de l’en-tête et du pied de page se mesure par rapport à la limite de la page. Dans le dictionnaire d’objet de page (ISO 32000-2 §7.7.3.3), l’entrée MediaBox définit la limite du support, et l’entrée CropBox définit la région visible à laquelle la page est rognée. La section 14.11.2 détaille la sémantique de ces limites de page. La marge d’en-tête que tu définis correspond au décalage depuis cette limite. Les marques d’en-tête et de pied de page ne sont pas un objet séparé ; elles font partie du flux Contents de chaque page, émis page par page (§7.7.3.3).

Surface de l’API

La surface de l’API est générée automatiquement à partir du PHPDoc. Ce recipe utilise les méthodes suivantes :

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — contenu de l’en-tête.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — typographie de l’en-tête et du pied de page.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — distance par rapport au bord de la page, en millimètres.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — active ou désactive l’habillage.

Exemple de code — Démarrage rapide

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

Exemple de code — Production

Voici l’exemple complet, prêt pour le harnais. Il respecte NEXTPDF_COOKBOOK_OUTPUT et ne fixe aucune entropie propre à l’exemple.

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

Cas limites & pièges

Configure l’habillage avant la première page. Un appel à setHeaderData() après addPage() ne redessine pas les pages précédentes ; configure donc l’habillage avant le premier addPage().
Marge d’en-tête et marge supérieure du contenu. La marge d’en-tête correspond à la distance entre l’en-tête et le bord de la page, et elle est indépendante de la marge supérieure du corps. Les deux peuvent se chevaucher si la marge supérieure du corps est plus petite que la bande d’en-tête ; prévois donc de l’espace.
Désactive l’habillage par document, pas par page. setPrintHeader(false) s’applique à l’ensemble du document. Il n’existe pas de bascule intégrée page par page. Une page de couverture sans habillage est un document distinct ou un choix de mise en page délibéré.
Chemin du logo. L’argument $logo de setHeaderData() attend un chemin de fichier local. Le chargeur d’images rejette les schémas d’URL (voir le recipe sur les images) ; passe donc un fichier local.

Performance

Le rendu de l’en-tête et du pied de page se fait page par page. Son coût dépend du contenu de l’habillage (quelques runs de texte), et non de la taille du corps ; il ajoute donc une surcharge négligeable au vidage de chaque page. Le budget de 2000 ms / 64 Mo couvre un document de plusieurs centaines de pages avec un habillage sur chaque page.

Notes de sécurité

Le titre et la description de l’en-tête sont restitués comme du texte de document. S’ils contiennent des données contrôlées par l’utilisateur, par exemple un nom de locataire, borne leur longueur et assainis-les comme le texte du corps. Ce recipe n’effectue aucune analyse ni aucun accès réseau.

Conformité

Énoncé	Spécification	Article
`MediaBox`, entrée du dictionnaire d’objet de page, définit la limite du support de la page par rapport à laquelle la géométrie de l’en-tête et du pied de page est mesurée.	ISO 32000-2	§7.7.3.3
`CropBox`, entrée du dictionnaire d’objet de page, est la région visible à laquelle la page est rognée.	ISO 32000-2	§7.7.3.3
Les marques d’en-tête et de pied de page font partie du flux `Contents` de chaque page.	ISO 32000-2	§7.7.3.3

Profil de reproductibilité — structurel. Le /ID du trailer et les atomes /CreationDate / /ModDate varient à chaque enregistrement. Le harnais retire ces atomes, puis compare la structure normalisée par qpdf. Ce recipe décrit la structure produite par NextPDF ; il n’affirme pas la conformité à ISO 32000-2 comme une revendication globale.

Contexte commercial

Sans objet. Les en-têtes et pieds de page répétés relèvent du cœur et ne sont pas verrouillés derrière Premium.