반복되는 페이지 머리글과 바닥글 추가

한눈에 보기

머리글(제목과 설명)과 바닥글을 한 번만 구성하면, 레이아웃 엔진이 자동 페이지 나눔으로 생성된 페이지까지 포함해 모든 페이지에 렌더링합니다. 데이터는 첫 번째 addPage() 전에 설정합니다. 페이지마다 머리글이나 바닥글을 직접 그릴 필요가 전혀 없습니다. 이 레시피는 examples/13-header-footer.php를 따릅니다.

설치

composer require nextpdf/core:^3

선택적 확장은 필요하지 않습니다. Layout concern의 머리글 및 바닥글 API는 1.0.0 이후로 안정적이며, 8.1–8.4 백포트 매트릭스에서 실행됩니다.

개념 개요

머리글과 바닥글은 페이지 장식 요소입니다. 레이아웃 엔진은 페이지가 플러시될 때 모든 페이지의 예약된 위쪽 및 아래쪽 영역에 이 요소들을 그립니다. setHeaderData()는 콘텐츠를 기록합니다. setHeaderFont(), setHeaderMargin(), setFooterFont(), setFooterMargin()은 타이포그래피와 페이지 가장자리로부터의 거리를 설정합니다. setPrintHeader(false)와 setPrintFooter(false)는 이러한 장식 요소가 필요 없는 문서에서 이를 끕니다.

머리글과 바닥글의 지오메트리는 페이지 경계를 기준으로 측정됩니다. 페이지 객체 사전(ISO 32000-2 §7.7.3.3)은 MediaBox 항목을 매체 경계로, CropBox 항목을 페이지가 잘려 보이는 표시 영역으로 정의합니다. 14.11.2 절은 이러한 페이지 경계의 의미를 자세히 설명합니다. 설정하는 머리글 여백은 해당 경계로부터의 오프셋입니다. 머리글과 바닥글 표시는 별도의 객체가 아니라 각 페이지의 Contents 스트림 일부이며, 페이지마다 생성됩니다(§7.7.3.3).

API 표면

API 표면은 PHPDoc에서 자동으로 생성됩니다. 이 레시피에서는 다음 메서드를 사용합니다.

setHeaderData(string $title = '', string $description = '', string $logo = '', float $logoWidth = 0): static — 머리글 콘텐츠.
setHeaderFont(string $family, float $size = 10): static / setFooterFont(string $family, float $size = 8): static — 머리글 및 바닥글 타이포그래피.
setHeaderMargin(float $margin): static / setFooterMargin(float $margin): static — 페이지 가장자리로부터의 거리(밀리미터 단위).
setPrintHeader(bool $enabled): static / setPrintFooter(bool $enabled): static — 장식 요소를 켜고 끕니다.

코드 샘플 — 빠른 시작

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

코드 샘플 — 프로덕션

다음은 완전한 예제이며 하니스에서 바로 사용할 수 있습니다. 이 예제는 NEXTPDF_COOKBOOK_OUTPUT을 따르며 자체적으로 어떤 엔트로피도 고정하지 않습니다.

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

엣지 케이스 및 주의 사항

첫 페이지 전에 장식 요소를 설정하세요. setHeaderData()를 addPage() 이후에 호출해도 이전 페이지는 다시 그려지지 않으므로, 첫 번째 addPage() 전에 설정하세요.
머리글 여백 대 콘텐츠 위쪽 여백. 머리글 여백은 페이지 가장자리로부터 머리글까지의 거리이며, 본문의 위쪽 여백과는 독립적입니다. 본문 위쪽 여백이 머리글 영역보다 작으면 둘이 겹칠 수 있으므로 여유 공간을 두세요.
장식 요소 비활성화는 페이지 단위가 아니라 문서 단위로 설정하세요. setPrintHeader(false)는 문서 전체에 적용됩니다. 기본 제공되는 페이지 단위 전환 기능은 없습니다. 장식 요소가 없는 표지 페이지는 별도의 문서이거나 의도적인 레이아웃 선택입니다.
로고 경로. $logo 인수는 setHeaderData()에 전달하는 로컬 파일 경로입니다. 이미지 로더는 URL 스킴을 거부하므로(이미지 레시피 참조), 로컬 파일을 전달하세요.

성능

머리글과 바닥글 렌더링은 페이지마다 수행됩니다. 그 비용은 본문 크기가 아니라 장식 요소의 콘텐츠(몇 개의 텍스트 런)에 비례하므로, 페이지 단위 플러시에 추가되는 오버헤드는 무시할 수 있는 수준입니다. 2000 ms / 64 MB 예산으로 모든 페이지에 장식 요소가 있는 수백 페이지 분량의 문서를 처리할 수 있습니다.

보안 참고 사항

머리글 제목과 설명은 문서 텍스트로 렌더링됩니다. 예를 들어 테넌트 이름처럼 사용자가 제어하는 데이터가 포함된 경우, 본문 텍스트를 다루는 것과 동일한 방식으로 길이를 제한하고 정제하세요. 이 레시피는 어떤 파싱도, 네트워크 접근도 수행하지 않습니다.

적합성

설명	사양	조항
`MediaBox` 페이지 객체 사전 항목은 header/footer 지오메트리의 측정 기준인 페이지 매체 경계를 정의합니다.	ISO 32000-2	§7.7.3.3
`CropBox` 페이지 객체 사전 항목은 페이지가 잘려 보이는 표시 영역입니다.	ISO 32000-2	§7.7.3.3
Header/footer 표시는 각 페이지의 `Contents` 스트림 일부입니다.	ISO 32000-2	§7.7.3.3

재현성 프로파일 — 구조적. 트레일러 /ID와 /CreationDate / /ModDate 원자는 저장할 때마다 달라집니다. 하니스는 이러한 원자를 제거한 다음 qpdf로 정규화된 구조를 비교합니다. 이 레시피는 NextPDF가 구조를 생성하는 방식을 설명할 뿐, ISO 32000-2 적합성을 포괄적으로 주장하지는 않습니다.

상업적 컨텍스트

해당 사항 없음. 반복되는 머리글과 바닥글은 Core 기능이며, Premium 게이트가 없습니다.