Aggiungere intestazioni e piè di pagina ripetuti

In breve

Configurare una sola volta un’intestazione (titolo e descrizione) e un piè di pagina: il motore di impaginazione li genera su ogni pagina, incluse quelle create dalle interruzioni di pagina automatiche. Impostare i dati prima del primo addPage(). Non è mai necessario disegnare l’intestazione o il piè di pagina pagina per pagina. Questa ricetta si basa su examples/13-header-footer.php.

Installazione

composer require nextpdf/core:^3

Non è richiesta alcuna estensione opzionale. L’API del concern Layout per intestazione e piè di pagina è stabile fin dalla versione 1.0.0 e funziona sulla matrice di backport 8.1–8.4.

Panoramica concettuale

L’intestazione e il piè di pagina sono elementi fissi della pagina. Il motore di impaginazione li disegna nelle bande superiore e inferiore riservate di ogni pagina al momento dell’emissione della pagina. setHeaderData() registra il contenuto. setHeaderFont(), setHeaderMargin(), setFooterFont() e setFooterMargin() impostano tipografia e distanza dal bordo della pagina. setPrintHeader(false) e setPrintFooter(false) disattivano gli elementi fissi per i documenti che non li richiedono.

La geometria dell’intestazione e del piè di pagina è misurata rispetto al confine della pagina. Il dizionario dell’oggetto pagina (ISO 32000-2 §7.7.3.3) definisce la voce MediaBox come confine del supporto e la voce CropBox come regione visibile a cui la pagina viene ritagliata. La sezione 14.11.2 descrive in dettaglio la semantica di questi confini di pagina. Il margine dell’intestazione configurato rappresenta lo scostamento da tale confine. I segni di intestazione e piè di pagina non sono un oggetto separato; fanno parte del flusso Contents di ciascuna pagina, emesso pagina per pagina (§7.7.3.3).

Superficie API

La superficie dell’API è generata automaticamente da PHPDoc. Questa ricetta utilizza i metodi seguenti:

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — contenuto dell’intestazione.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — tipografia dell’intestazione e del piè di pagina.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — distanza dal bordo della pagina, in millimetri.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — attivano/disattivano gli elementi fissi.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Questo è l’esempio completo, pronto per l’harness. Rispetta NEXTPDF_COOKBOOK_OUTPUT e non introduce entropia propria.

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

Casi limite e insidie

Impostare gli elementi fissi prima della prima pagina. Una chiamata a setHeaderData() dopo addPage() non ridisegna le pagine precedenti; configurarla quindi prima del primo addPage().
Margine dell’intestazione rispetto al margine superiore del contenuto. Il margine dell’intestazione indica la distanza dal bordo della pagina ed è indipendente dal margine superiore del corpo. I due possono sovrapporsi se il margine superiore del corpo è più piccolo della banda dell’intestazione, quindi lasciare spazio sufficiente.
Disattivare gli elementi fissi per documento, non per pagina. setPrintHeader(false) si applica all’intero documento. Non esiste un’opzione integrata per attivarli o disattivarli su una singola pagina. Una copertina senza elementi fissi richiede un documento separato o una scelta di impaginazione deliberata.
Percorso del logo. L’argomento $logo di setHeaderData() è un percorso di file locale. Il caricatore di immagini rifiuta gli schemi URL (vedere la ricetta sulle immagini), quindi passare un file locale.

Prestazioni

Il rendering dell’intestazione e del piè di pagina viene eseguito pagina per pagina. Il suo costo scala con il contenuto degli elementi fissi (alcune sequenze di testo), non con le dimensioni del corpo, quindi aggiunge un overhead trascurabile all’emissione di ciascuna pagina. Il budget di 2000 ms / 64 MB copre un documento di diverse centinaia di pagine con elementi fissi su ogni pagina.

Note sulla sicurezza

Il titolo e la descrizione dell’intestazione vengono emessi come testo del documento. Se contengono dati controllati dall’utente, ad esempio il nome di un tenant, limitarne la lunghezza e sanificarli allo stesso modo del testo del corpo. Questa ricetta non esegue parsing né accessi di rete.

Conformità

Dichiarazione	Specifica	Clausola
`MediaBox`, la voce del dizionario dell’oggetto pagina, definisce il confine del supporto della pagina rispetto al quale è misurata la geometria di header/footer.	ISO 32000-2	§7.7.3.3
`CropBox`, la voce del dizionario dell’oggetto pagina, è la regione visibile a cui la pagina viene ritagliata.	ISO 32000-2	§7.7.3.3
I segni di header/footer fanno parte del flusso `Contents` di ciascuna pagina.	ISO 32000-2	§7.7.3.3

Profilo di riproducibilità — strutturale. L’atomo /ID del trailer e gli atomi /CreationDate / /ModDate variano a ogni salvataggio. L’harness rimuove tali atomi, quindi confronta la struttura normalizzata da qpdf. Questa ricetta descrive come NextPDF produce la struttura; non formula una dichiarazione generale di conformità a ISO 32000-2.

Contesto commerciale

Non applicabile. Le intestazioni e i piè di pagina ripetuti sono una funzionalità Core, senza alcun vincolo Premium.