자동 페이지 나누기로 여러 페이지 문서 만들기

한눈에 보기

여러 페이지에 걸쳐 콘텐츠가 이어지는 문서를 만듭니다. 콘텐츠는 작성 흐름에 따라 순차적으로 추가합니다. setAutoPageBreak()가 활성화되어 있으면 커서가 아래쪽 여백에 도달할 때 레이아웃 엔진이 새 페이지를 자동으로 시작합니다. save() 이후 getNumPages()로 최종 페이지 수를 읽어 옵니다. 이 레시피는 examples/05-multi-page.php를 따릅니다.

save()로 문서를 저장하는 동안 엔진은 각 페이지의 마크를 콘텐츠 스트림에 기록합니다. ISO 32000-2 §7.7.3.3은 페이지의 Contents를 하나의 스트림으로, 또는 순서대로 연결된 스트림 배열로 정의합니다. 따라서 여러 페이지 출력은 단일 버퍼가 아니라 페이지 객체의 시퀀스입니다.

설치

composer require nextpdf/core:^3

선택적 확장 모듈은 필요하지 않습니다. 이 레시피는 PHP 8.1~8.4 백포트 매트릭스 전반에서 실행됩니다. getNumPages()와 setAutoPageBreak()은 모두 1.0.0부터 안정적입니다.

개념 개요

NextPDF 문서는 페이지 트리입니다. 콘텐츠를 추가하면 내부 커서(getY())가 이동합니다. 자동 페이지 나누기가 켜져 있으면 엔진은 각 콘텐츠 블록 앞에서 남은 세로 공간을 확인합니다. 블록이 아래쪽 여백을 침범하지 않고 들어가지 못하면 엔진은 현재 페이지를 플러시하고 addPage()를 자동으로 호출합니다. setAutoPageBreak()에 전달하는 아래쪽 여백이 트리거 임계값입니다.

미디어 박스와 같은 페이지 수준 속성은 상속될 수 있습니다. ISO 32000-2 §7.7.3.4은 페이지 객체에서 생략된 속성이 상위 페이지 트리 노드에서 해결됨을 명시합니다. NextPDF는 문서 전체에 일관된 페이지 크기를 하나 설정하므로 생성되는 모든 페이지가 동일한 형상을 공유하며 페이지마다 반복할 필요가 없습니다.

API 표면

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

Document::createStandalone(): self — 독립된 문서를 생성합니다.
setAutoPageBreak(bool $enabled, float $margin = 20): static — 자동 페이지 나누기를 활성화합니다. $margin은 밀리미터 단위의 아래쪽 여백 트리거 값입니다.
addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait): static — 첫 페이지와 명시적으로 지정한 페이지를 시작합니다.
multiCell(...): static / cell(...): static — 흐름형 텍스트 블록 또는 고정 텍스트 블록을 출력합니다. 페이지 나누기 검사는 이러한 블록을 측정합니다.
getNumPages(): int — 레이아웃 이후의 페이지 수입니다.

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setAutoPageBreak(true, margin: 25);
$doc->addPage();

$doc->setFont('helvetica', '', 11);
for ($i = 1; $i <= 60; $i++) {
    $doc->multiCell(0, 7, "Line {$i}: content flows until the page is full, "
        . 'then the engine starts a new page automatically.');
}

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/multi-page.pdf');
echo 'Pages: ' . $doc->getNumPages() . "\n";

코드 샘플 — 프로덕션

다음은 하니스에서 바로 실행할 수 있는 완전한 예제입니다. 이 예제는 하니스가 설정하는 NEXTPDF_COOKBOOK_OUTPUT를 따르므로 PDF를 STDOUT으로 출력하지 마십시오. 이 예제는 자체적으로 어떤 엔트로피도 고정하지 않습니다. 하니스가 이 예제를 실행하면 DeterministicMode가 클록, /ID, 브랜딩을 고정합니다.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Multi-Page Document');

// Enable automatic page breaks. The 25 mm bottom margin is the trigger:
// when the cursor would cross it, the engine flushes the page and adds
// a new one before the next block is drawn.
$doc->setAutoPageBreak(true, margin: 25);
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Multi-Page Document Example', newLine: true);
$doc->ln(5);

for ($chapter = 1; $chapter <= 3; $chapter++) {
    $doc->setFont('helvetica', 'B', 14);
    $doc->cell(0, 10, "Chapter {$chapter}: Lorem Ipsum", newLine: true);
    $doc->setFont('helvetica', '', 11);

    for ($para = 1; $para <= 5; $para++) {
        $text = "Paragraph {$para} of Chapter {$chapter}. "
            . 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. '
            . 'Sed do eiusmod tempor incididunt ut labore et dolore magna '
            . 'aliqua. Ut enim ad minim veniam, quis nostrud exercitation '
            . 'ullamco laboris nisi ut aliquip ex ea commodo consequat.';
        $doc->multiCell(0, 7, $text);
        $doc->ln(3);
    }
    $doc->ln(5);
}

// The harness sets NEXTPDF_COOKBOOK_OUTPUT; honour it. STDOUT stays free
// for progress text only.
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/multi-page.pdf';
$doc->save($out);

echo 'Created multi-page.pdf with ' . $doc->getNumPages() . " pages\n";

엣지 케이스 및 주의 사항

자동 페이지 나누기 비활성화. setAutoPageBreak(false, …)을 사용하면 아래쪽 여백을 넘어가는 콘텐츠는 다음 페이지로 흐르지 않고 현재 페이지에서 잘리며, 문서는 단일 페이지를 유지합니다. 페이지를 넘어 흐르는 콘텐츠를 사용하려면 이를 활성화하십시오.
페이지보다 높은 단일 블록. multiCell의 텍스트가 인쇄 가능한 높이를 초과하면 엔진은 이를 내부적으로 분할합니다. 하지만 사용 가능한 영역보다 높은 단일 분할 불가능 블록(예: 높은 이미지)은 한 번 배치된 뒤 넘칩니다. 직접 분할하십시오.
첫 addPage()는 여전히 필요합니다. 페이지가 없을 때 cell()은 필요에 따라 addPage()를 호출합니다. 그렇더라도 첫 페이지의 크기와 방향이 결정적으로 정해지도록 addPage()를 명시적으로 호출하십시오.
여백 단위. setAutoPageBreak() 여백은 기본 단위 체계에서 포인트가 아니라 밀리미터 단위입니다.

성능

getNumPages()는 O(1)입니다. 이는 카운터를 읽을 뿐 다시 레이아웃하지 않습니다. 메모리는 페이지 수가 아니라 보존된 콘텐츠에 비례합니다. 엔진은 완료된 페이지가 만들어지는 대로 출력 버퍼로 플러시합니다. 이는 단일 패스 스트리밍 모델(ADR-001)입니다. 2000 ms / 64 MB 예산은 참조 호스트에서 수백 페이지 분량의 텍스트 문서를 처리할 수 있습니다.

보안 참고 사항

이 레시피는 코드에서 제공한 텍스트만 기록합니다. 입력 파싱, 네트워크 접근, 역직렬화는 수행하지 않습니다. 외부에서 가져온 텍스트는 신뢰할 수 없는 것으로 취급하고 렌더링 전에 길이를 제한하십시오. 엔진은 애플리케이션 수준의 콘텐츠 크기 제한을 대신 부과하지 않습니다.

적합성

서술	사양	조항
페이지의 `Contents`는 단일 스트림이거나 순서대로 연결된 스트림 배열입니다.	ISO 32000-2	§7.7.3.3
페이지 객체에서 생략된 상속 가능한 페이지 속성은 상위 페이지 트리 노드에서 해결됩니다.	ISO 32000-2	§7.7.3.4
트레일러 `/ID`는 두 개의 바이트 문자열로 된 파일 식별자입니다(PDF 2.0 에서 필수).	ISO 32000-2	§7.5.5

재현성 프로파일 — 구조적(비트 단위가 아닌 이유). 저장된 모든 문서에는 트레일러 /ID가 포함되며, 해당 두 바이트 문자열은 파일 식별자입니다(위의 ISO 32000-2 §7.5.5). 두 번째 요소는 실행 간 안정적이지 않으므로 동일한 콘텐츠라도 실행마다 원시 바이트가 달라집니다. 하니스는 qpdf로 정규화된 구조를 비교하며, 이는 /ID, /CreationDate, /ModDate를 제거합니다. 이 레시피는 NextPDF가 구조를 생성하는 방식을 설명합니다. 이 레시피는 ISO 32000-2 적합성을 포괄적으로 주장하지 않습니다.

상업적 맥락

해당 없음. 자동 페이지 나누기를 사용한 여러 페이지 구성은 Premium 게이트가 없는 Core 기능입니다.