Menambahkan header dan footer berulang pada halaman

Sekilas pandang

Konfigurasikan header (judul dan deskripsi) serta footer cukup sekali. Mesin tata letak merendernya di setiap halaman, termasuk halaman yang dihasilkan oleh pemenggalan halaman otomatis. Tetapkan datanya sebelum addPage() yang pertama. Anda tidak perlu menggambar header atau footer di setiap halaman. Resep ini mengikuti examples/13-header-footer.php.

Instalasi

composer require nextpdf/core:^3

Anda tidak memerlukan ekstensi opsional. Antarmuka pemrograman aplikasi (API) header dan footer pada concern Layout stabil sejak 1.0.0. API ini berjalan pada matriks backport 8.1–8.4.

Gambaran konseptual

Header dan footer adalah elemen halaman yang tetap. Mesin tata letak menggambarnya pada pita atas dan bawah yang tersedia di setiap halaman saat halaman tersebut di-flush. setHeaderData() menyimpan kontennya. setHeaderFont(), setHeaderMargin(), setFooterFont(), dan setFooterMargin() menetapkan tipografi dan jarak dari tepi halaman. setPrintHeader(false) dan setPrintFooter(false) menonaktifkan elemen tetap tersebut untuk dokumen yang tidak membutuhkannya.

Geometri header dan footer diukur relatif terhadap batas halaman. Kamus objek halaman (ISO 32000-2 §7.7.3.3) mendefinisikan entri MediaBox sebagai batas medium dan entri CropBox sebagai wilayah yang terlihat tempat halaman dipotong. Bagian 14.11.2 mendefinisikan semantik batas-batas halaman tersebut. Margin header yang Anda tetapkan adalah offset dari batas tersebut. Tanda header dan footer bukan objek terpisah; tanda tersebut merupakan bagian dari stream Contents setiap halaman dan di-emit per halaman (§7.7.3.3).

Cakupan API

Cakupan API ini dihasilkan dari PHPDoc. Resep ini menggunakan metode berikut:

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — menetapkan konten header.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — menetapkan tipografi header dan footer.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — menetapkan jarak dari tepi halaman, dalam milimeter.
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — mengaktifkan atau menonaktifkan elemen tetap.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Contoh lengkap yang siap untuk harness ini mematuhi NEXTPDF_COOKBOOK_OUTPUT dan tidak menyisipkan entropi sendiri.

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

Kasus tepi & jebakan

Tetapkan elemen tetap sebelum halaman pertama. Memanggil setHeaderData() setelah addPage() tidak akan menggambar ulang halaman sebelumnya, jadi konfigurasikan sebelum addPage() yang pertama.
Margin header versus margin atas konten. Margin header adalah jarak header dari tepi halaman. Margin ini terpisah dari margin atas badan dokumen. Keduanya dapat saling tumpang tindih jika margin atas badan lebih kecil daripada pita header, jadi sisakan ruang yang cukup.
Nonaktifkan elemen tetap per dokumen, bukan per halaman. setPrintHeader(false) berlaku untuk seluruh dokumen. Tidak ada sakelar bawaan per halaman. Untuk halaman sampul tanpa elemen tetap, gunakan dokumen terpisah atau pilih tata letak secara sengaja.
Jalur logo. Argumen $logo pada setHeaderData() adalah jalur berkas lokal. Pemuat gambar menolak skema URL (lihat resep gambar), jadi gunakan berkas lokal.

Performa

Perenderan header dan footer berjalan per halaman. Biayanya berskala dengan konten elemen tetap (beberapa text run), bukan dengan ukuran badan dokumen. Hal ini hanya menambah overhead yang dapat diabaikan pada setiap flush halaman. Anggaran 2000 ms / 64 MB mencakup dokumen ratusan halaman dengan elemen tetap di setiap halaman.

Catatan keamanan

Judul dan deskripsi header dirender sebagai teks dokumen. Jika keduanya memuat data yang dikendalikan pengguna, seperti nama tenant, batasi panjangnya dan lakukan sanitasi dengan cara yang sama seperti Anda memperlakukan teks badan. Resep ini tidak melakukan parsing maupun akses jaringan.

Konformansi

Pernyataan	Spesifikasi	Klausa
Entri kamus objek halaman `MediaBox` mendefinisikan batas medium halaman yang menjadi acuan pengukuran geometri header/footer.	ISO 32000-2	§7.7.3.3
Entri kamus objek halaman `CropBox` adalah wilayah yang terlihat tempat halaman dipotong.	ISO 32000-2	§7.7.3.3
Tanda header/footer merupakan bagian dari stream `Contents` setiap halaman.	ISO 32000-2	§7.7.3.3

Profil reproduktibilitas — struktural. Atom trailer /ID dan atom /CreationDate / /ModDate berbeda-beda setiap kali penyimpanan. Harness menghapus atom-atom tersebut, lalu membandingkan struktur yang telah dinormalkan dengan qpdf. Resep ini menjelaskan cara NextPDF menghasilkan struktur tersebut. Resep ini tidak menyatakan konformansi ISO 32000-2 sebagai klaim menyeluruh.

Konteks komersial

Tidak berlaku. Header dan footer berulang merupakan kemampuan Core, tanpa gerbang Premium.