머리글, 바닥글, 여러 페이지 문서

한 페이지로는 부족할 때가 많습니다. 이 튜토리얼에서는 스스로 세 페이지까지 늘어나는 문서를 작성합니다. 또한 모든 페이지에 반복되는 머리글과, 페이지 번호를 보여 주는 바닥글을 추가합니다.

무엇을 만들까요

01-multipage.php라는 스크립트 하나를 작성합니다. 이 스크립트는 세 페이지짜리 여행 일지를 PDF(Portable Document Format) 파일로 생성합니다:

일지 항목은 한 페이지에서 다음 페이지로 자동으로 이어집니다. 페이지가 어디서 끝나는지 직접 지정하지 않으며, 엔진이 결정합니다.
머리글은 페이지 상단에 있는 띠로, 모든 페이지에 반복됩니다. 여기서는 문서 제목을 표시합니다.
바닥글은 하단에 있는 짝이 되는 띠입니다. 여기서는 페이지 번호를 1 / 3, 2 / 3, 3 / 3 형태로 표시합니다.

모든 것은 nextpdf/core 패키지 하나만으로 실행됩니다. 글꼴 파일도, 추가 확장 모듈도, 네트워크도 필요하지 않습니다.

1단계: 세 페이지 여행 일지 만들기

이 스크립트에서는 두 가지 개념이 모든 일을 처리합니다.

첫 번째는 자동 페이지 나누기입니다. 엔진은 텍스트를 기록하면서 커서, 곧 다음 줄이 놓일 페이지상의 위치를 추적합니다. setAutoPageBreak(true, margin: 25)는 엔진에게 그 커서를 지켜보도록 지시합니다. 커서가 아래쪽 가장자리로부터 25포인트(약 3분의 1인치) 이내로 들어오면 엔진은 해당 페이지를 닫고 새 페이지를 시작합니다.

두 번째는 페이지 장식 요소, 곧 머리글과 바닥글입니다. 이들은 첫 페이지 전에 한 번만 정의합니다. setHeaderData()는 상단 띠에 들어갈 제목과 짧은 설명을 기록합니다. 글꼴과 여백 호출은 글자 모양과 페이지 가장자리로부터의 거리를 정합니다. 그러면 엔진은 자신이 만드는 모든 페이지에, 스스로 추가하는 페이지 까지 포함하여 이 장식 요소를 그립니다.

프로젝트 폴더에 01-multipage.php를 만듭니다:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// Make sure the output folder exists next to this script.
@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('NextPDF Travel Journal');

// Configure the header and footer BEFORE the first page.
// The engine repeats them on every page for you.
$document->setHeaderData(title: 'NextPDF Travel Journal', description: 'A multi-page tutorial document');
$document->setHeaderFont('helvetica', 10);
$document->setHeaderMargin(5);
$document->setFooterFont('helvetica', 8);
$document->setFooterMargin(10);

// Turn on automatic page breaks. When the text cursor gets within
// 25 points of the bottom edge, the engine starts a new page.
$document->setAutoPageBreak(true, margin: 25);

$document->addPage();

$document->setFont('helvetica', 'B', 18);
$document->cell(0, 12, 'Travel journal: three days on the coast', newLine: true);
$document->ln(5);

$days = [
    1 => 'We followed the shoreline north and counted seventeen lighthouses.',
    2 => 'Rain moved in before noon, so we sketched the harbor from a cafe window.',
    3 => 'On the last morning the fog lifted and the whole bay turned silver.',
];

foreach ($days as $day => $highlight) {
    $document->setFont('helvetica', 'B', 14);
    $document->cell(0, 10, "Day {$day}", newLine: true);

    $document->setFont('helvetica', '', 11);
    for ($entry = 1; $entry <= 12; $entry++) {
        $text = "Entry {$entry} of day {$day}. {$highlight} "
            . 'The trail hugged the cliffs for most of the afternoon, and every '
            . 'turn opened another view of the water. We stopped often to take '
            . 'notes, compare maps, and argue happily about where to eat dinner. '
            . 'By the time we reached the guesthouse, our boots were soaked and '
            . 'our notebooks were full.';
        $document->multiCell(0, 7, $text);
        $document->ln(3);
    }
    $document->ln(5);
}

// Ask the engine how many pages the layout produced, then save.
$pages = $document->getNumPages();
$document->save(__DIR__ . '/out/travel-journal.pdf');

echo "Wrote out/travel-journal.pdf with {$pages} pages\n";

php 01-multipage.php로 실행합니다. 스크립트는 한 줄을 출력합니다:

Wrote out/travel-journal.pdf with 3 pages

out/travel-journal.pdf를 열어 스크롤해 보십시오. 제목 띠는 세 페이지 모두 상단에 자리하고, 페이지 번호는 오른쪽 아래에서 순서대로 올라갑니다.

방금 무슨 일이 일어났나요

작성 루프는 페이지를 전혀 언급하지 않습니다. 각 날짜 제목은 cell()로 기록하는데, 이는 보이지 않는 상자 안에 한 줄을 넣습니다. 항목은 multiCell()로 기록하며, 이는 긴 텍스트를 필요한 만큼 여러 줄로 나눠 줍니다. 서른여섯 개의 항목은 한 페이지에 들어가지 않으므로 자동 페이지 나누기가 두 번 실행됩니다. 그래서 일지는 정확히 세 페이지가 됩니다.

머리글과 바닥글은 첫 addPage() 호출 전에 구성했습니다. 이 순서가 중요합니다. 이미 그려진 페이지는 나중에 갱신되지 않습니다. 장식 요소를 먼저 구성하면 모든 페이지가 일관되게 출력됩니다.

페이지 번호를 직접 그린 적은 없습니다. 바닥글은 기본적으로 이를 출력하며, 여러분은 글꼴과 페이지 가장자리로부터의 거리만 골랐습니다. 엔진은 페이지를 기록하는 동안에는 아직 최종 페이지 수를 알 수 없습니다. 그래서 각 바닥글에 자리 표시자를 남겨 두었다가 저장할 때 실제 총계를 채워 넣습니다.

작은 두 가지 세부 사항이 스크립트를 마무리합니다. @mkdir는 out 폴더를 만들며, @ 기호는 폴더가 이미 있을 때 PHP가 조용히 넘어가게 합니다. getNumPages()는 레이아웃이 몇 페이지를 만들었는지 엔진에 물으므로, 마지막 메시지가 실제 페이지 수를 알려 줄 수 있습니다.

문제가 생겼다면

require 줄에서 “failed to open stream” 오류가 나면 스크립트가 vendor/autoload.php를 찾지 못한 것입니다. vendor/가 들어 있는 프로젝트 폴더 안에서 실행하십시오.
모든 것이 한 페이지에 몰려 있고 텍스트 끝이 잘렸나요? 그렇다면 자동 페이지 나누기가 꺼져 있는 것입니다. setAutoPageBreak(true, margin: 25) 줄을 유지하고, 작성 루프 위에 두십시오.
글꼴 패밀리 이름을 잘못 입력하면 찾지 못한 글꼴을 알려 주는 예외가 발생합니다. helvetica 철자를 확인하고, 더 깊은 글꼴 문제는 글꼴 및 태깅을 참고하십시오.
그 밖의 문제는 문제 해결 허브가 증상을 원인에 연결해 주며, 오류 참조는 엔진의 일반 예외와 각 예외에서 복구하는 방법을 설명합니다.

이제 문서는 어떤 길이로든 늘어나면서도 완성된 모습을 유지할 수 있습니다. 다음 튜토리얼에서는 콘텐츠를 HTML(Hypertext Markup Language)로 작성하고 엔진이 이를 페이지로 바꾸도록 합니다.

오늘 다룬 주제를 더 세밀하게 제어하고 싶다면, 두 가지 레시피가 더 깊이 들어갑니다:

여러 페이지 문서 만들기는 엣지 케이스를 포함해 페이지 나누기를 자세히 다룹니다.
반복되는 페이지 머리글과 바닥글 추가하기는 머리글과 바닥글을 끄는 방법을 포함해 모든 설정을 하나하나 안내합니다.