텍스트, 폰트, 페이지 기초

첫 번째 튜토리얼에서는 한 줄의 텍스트가 담긴 페이지를 렌더링했습니다. 이번에는 페이지 자체와 그 위의 텍스트를 직접 제어합니다. 페이지 크기를 선택하고, 제목과 단락을 작성하며, 엔진에 내장된 폰트로 이를 스타일링합니다.

만들게 될 결과물

작은 스크립트 두 개를 작성합니다. 각 스크립트는 한 페이지짜리 Portable Document Format(PDF) 파일을 생성합니다:

• 01-text-basics.php는 색이 지정된 제목, 줄바꿈된 단락, 세 가지 정렬 예시가 있는 A4 세로 페이지를 렌더링합니다.
• 02-fonts.php는 내장 폰트 패밀리 두 개를 여러 크기로 비교하는 샘플러 페이지를 렌더링합니다.

모든 작업은 nextpdf/core 패키지만으로 실행됩니다. 폰트 파일도, 추가 확장도, 네트워크도 필요하지 않습니다. 아직 프로젝트를 설정하지 않았다면, 먼저 첫 번째 튜토리얼을 따라 진행한 뒤 돌아오세요.

1단계: A4 페이지에서 텍스트 스타일 지정하기

모든 페이지에는 크기와 방향이 있습니다. A4는 널리 쓰이는 국제 용지 크기이고, Letter는 그에 대응하는 미국 용지 크기입니다. 방향은 세로(portrait, 곧게 선 방향) 또는 가로(landscape, 옆으로 누운 방향) 중 하나입니다. 페이지를 시작할 때 이 두 가지 선택을 addPage()에 전달합니다.

그런 다음 세 가지 메서드가 실제로 글자를 씁니다. setFont()는 뒤따르는 텍스트의 서체와 크기를 선택합니다. cell()은 보이지 않는 상자 안에 한 줄을 씁니다. multiCell()은 더 긴 텍스트를 필요한 만큼의 줄로 줄바꿈합니다. 두 메서드 모두에서 너비 0은 “오른쪽 여백까지 전부 사용”을 의미합니다.

나머지 두 호출이 모양을 담당합니다. setTextColor()는 0부터 255까지의 빨강, 초록, 파랑 값을 받으며, 다시 변경하기 전까지 계속 적용됩니다. 이름이 정해진 선택지의 고정 목록인 Alignment 열거형(enum)은 Left, Center, Right, Justify를 제공합니다.

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

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\Orientation;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Text basics');
$document->addPage(PageSize::A4(), Orientation::Portrait);

// A colored heading. The values are red, green, and blue, each 0 to 255.
$document->setFont('helvetica', 'B', 20);
$document->setTextColor(30, 64, 175);
$document->cell(0, 14, 'Project kickoff notes', newLine: true);
$document->ln(4);

// Back to black for the body text.
$document->setTextColor(0, 0, 0);
$document->setFont('helvetica', '', 11);
$document->multiCell(
    0,
    7,
    'Welcome to the second tutorial. This paragraph is written with '
        . 'multiCell(), so the engine wraps the words onto as many lines '
        . 'as the page width requires.',
);
$document->ln(4);

$document->multiCell(
    0,
    7,
    'Justified text stretches the spaces so both edges line up. It is a '
        . 'good fit for report bodies and other long passages.',
    align: Alignment::Justify,
);
$document->ln(6);

// One line each: left, centered, and right.
$document->setFont('helvetica', 'I', 11);
$document->cell(0, 8, 'Left-aligned line', newLine: true, align: Alignment::Left);
$document->cell(0, 8, 'Centered line', newLine: true, align: Alignment::Center);
$document->cell(0, 8, 'Right-aligned line', newLine: true, align: Alignment::Right);

$document->save(__DIR__ . '/out/text-basics.pdf');

echo "Wrote out/text-basics.pdf\n";

php 01-text-basics.php로 실행합니다. 스크립트는 Wrote out/text-basics.pdf를 출력하고, 새로 생긴 out/ 폴더에 파일이 나타납니다.

방금 일어난 일

addPage(PageSize::A4(), Orientation::Portrait)는 어떤 텍스트를 쓰기 전에 페이지를 만들었습니다. 대신 Orientation::Landscape를 전달하면 같은 페이지가 옆으로 눕습니다. PageSize::A5()나 PageSize::Letter()처럼 이름이 붙은 다른 크기도 같은 방식으로 동작합니다.

setFont('helvetica', 'B', 20)는 20포인트 굵은 Helvetica를 선택했습니다. 포인트(pt)는 전통적인 인쇄 단위로, 72포인트가 1인치입니다. cell() 호출이 제목을 쓸 때 setTextColor(30, 64, 175)가 활성 상태였기 때문에 제목은 파란색입니다. 그다음의 setTextColor(0, 0, 0)은 이후의 모든 것을 다시 검은색으로 전환했습니다.

두 개의 multiCell() 호출은 각자의 단락을 자동으로 줄바꿈했습니다. 양쪽 맞춤(justified) 단락은 단락의 마지막 줄을 제외하고 양쪽 가장자리가 맞도록 단어 간격을 늘립니다. 블록 사이에서 ln()은 여백을 더하기 위해 쓰기 위치를 아래로 이동했습니다. 마지막으로 save()가 파일을 만들어 out/에 기록했습니다.

이 메서드들이 받는 모든 매개변수는 폰트와 정렬로 텍스트 구성하기에서 확인하세요.

2단계: 내장 폰트 중에서 선택하기

엔진에는 세 가지 텍스트 패밀리가 내장되어 있습니다. Helvetica, Times, Courier입니다. Helvetica는 산세리프 서체로, 글자에 작은 끝맺음 획(세리프)이 없습니다. Times는 세리프 서체로, 길고 인쇄물 같은 문단에서 읽기 좋습니다. Courier는 고정 너비라서 코드 목록과 영수증에 적합합니다. 이 패밀리들은 내장되어 있으므로 스크립트에 폰트 파일이 전혀 필요하지 않습니다.

setFont()의 스타일 인수는 한 글자짜리 플래그를 조합합니다. 'B'는 굵게, 'I'는 기울임, 'U'는 밑줄입니다. 빈 문자열은 보통체를 의미하며, 플래그를 조합할 수 있어 'BI'는 굵은 기울임체가 됩니다.

내장 패밀리는 라틴 기반 텍스트를 지원합니다. 다른 문자 체계나 여러분만의 브랜드 서체를 사용하려면, 폰트 임베드 및 서브셋 레시피가 보여주듯이 폰트 파일을 등록합니다(서브셋은 실제로 사용한 문자만 남기므로 파일이 작게 유지됩니다). 폰트 지원 매트릭스는 엔진이 허용하는 모든 폰트 형식을 나열합니다.

첫 번째 스크립트 옆에 02-fonts.php를 만듭니다:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Font sampler');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 14, 'Built-in font sampler', newLine: true);
$document->ln(4);

// Helvetica: a sans-serif face, a solid default for labels and headings.
$document->setFont('helvetica', 'B', 14);
$document->cell(0, 10, 'Helvetica', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('helvetica', '', (float) $size);
    $document->cell(0, $size * 0.8, "Helvetica sample at {$size}pt.", newLine: true);
}
$document->setFont('helvetica', 'BI', 12);
$document->cell(0, 9, 'Helvetica bold italic for emphasis.', newLine: true);
$document->ln(6);

// Times: a serif face that suits long, print-like passages.
$document->setFont('times', 'B', 14);
$document->cell(0, 10, 'Times', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('times', '', (float) $size);
    $document->cell(0, $size * 0.8, "Times sample at {$size}pt.", newLine: true);
}
$document->setFont('times', 'I', 12);
$document->cell(0, 9, 'Times italic for quotations.', newLine: true);

$document->save(__DIR__ . '/out/font-sampler.pdf');

echo "Wrote out/font-sampler.pdf\n";

php 02-fonts.php로 실행하고 out/font-sampler.pdf를 엽니다. 같은 예시 문장이 두 패밀리 사이에서 성격이 달라지고 세 가지 크기로 커지는 것을 볼 수 있습니다.

방금 일어난 일

인수 없는 addPage()는 세로 방향의 기본 페이지 설정을 사용했으므로, 모든 스크립트가 크기를 일일이 명시할 필요는 없습니다. 각 setFont() 호출은 페이지 중간에서 활성 패밀리, 스타일, 크기를 전환했으며, 폰트는 다음 setFont() 호출 전까지 활성 상태로 유지됩니다.

반복문은 setFont()가 소수를 받기 때문에 크기를 (float)로 캐스팅합니다. 줄 높이는 폰트 크기($size * 0.8)에 비례하므로, 텍스트가 클수록 줄도 높아져 아무것도 겹치지 않습니다. 'times'를 'courier'로 바꾸고 스크립트를 다시 실행해 세 번째 패밀리를 확인해 보세요.

문제가 생겼다면

• “class not found”나 오토로드 오류는 보통 스크립트가 vendor/autoload.php를 찾지 못했다는 뜻입니다. vendor/가 있는 프로젝트 폴더 안에서 실행하세요.
• 패밀리 이름을 잘못 입력하면, 찾을 수 없는 폰트 이름을 알려주는 예외가 발생합니다. 철자를 확인하세요. helvetica, times, courier.
• 문제 해결 허브는 흔한 해결책을 모아 두었으며, 폰트와 태깅은 폰트 문제를 깊이 있게 다룹니다.
• 모든 엔진 예외는 각 예외가 담고 있는 컨텍스트와 복구 방법과 함께 오류 참조에 문서화되어 있습니다.

다음 단계

이제 여러분은 페이지를 구성하고, 텍스트를 스타일링하고, 의도를 가지고 폰트를 선택할 수 있습니다. 다음 튜토리얼에서는 페이지에 이미지를 배치하고 표와 목록으로 콘텐츠를 정리합니다.