NextPDF를 설정하고 첫 PDF 렌더링하기

NextPDF는 PDF(Portable Document Format) 파일을 만드는 PHP 라이브러리입니다. 이 튜토리얼에서는 NextPDF를 빈 폴더에 설치하고 첫 한 페이지짜리 문서를 렌더링합니다. 터미널과 약 10분의 시간이 필요합니다.

만들게 될 결과물

01-hello.php라는 스크립트 하나만 포함하는 작은 프로젝트를 만듭니다. 이 스크립트는 굵은 제목 줄과 단락 하나가 있는 한 페이지를 렌더링합니다. 그 결과를 out/hello.pdf로 저장합니다. 그 과정에서 설치가 정상인지 확인하는 두 개의 명령을 배웁니다.

이 페이지에서는 하나의 설치 경로, 즉 빈 폴더와 엔진 패키지를 다룹니다. 프레임워크 어댑터, 브라우저 기반 렌더러, Python 클라이언트 같은 다른 경로도 있습니다. 그러한 경로는 설치 와 경로 선택에 있습니다. 오늘은 그것들이 필요하지 않습니다.

1단계: 프로젝트를 만들고 NextPDF 설치하기

Composer는 PHP의 패키지 관리자입니다. 라이브러리를 프로젝트로 다운로드하고 오토로더를 생성합니다. 오토로더는 라이브러리의 클래스를 대신 찾아 주는 작은 PHP 파일이므로, 긴 include 목록을 작성할 필요가 없습니다.

터미널을 열고 다음 세 개의 명령을 실행합니다.

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer는 패키지를 해결하고 다운로드하는 동안 진행 상황을 출력합니다. 실제 출력되는 줄은 Composer 버전과 로컬 캐시에 따라 다릅니다. 설치가 성공하면 오류 텍스트 없이 종료되며, 대략 다음과 같이 표시됩니다.

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

방금 일어난 일

Composer는 폴더 안에 세 가지를 만들었습니다. composer.json은 프로젝트가 엔진에 의존한다는 것을 기록합니다. composer.lock은 설치된 정확한 버전을 고정하므로, 나중에 설치해도 동일한 코드가 해결됩니다. vendor/ 폴더에는 vendor/autoload.php를 포함하여 다운로드된 패키지가 들어 있습니다. 스크립트는 이 파일 하나만 읽어 들이면 모든 엔진 클래스를 사용할 수 있게 됩니다.

Composer는 설치 중에 PHP 설정도 확인했습니다. 엔진은 필요한 PHP 확장 기능을 선언합니다. 확장 기능은 PHP에 내장된 선택적 모듈입니다. 하나라도 누락되면, Composer는 손상된 설치 상태로 남겨 두는 대신 처리를 멈추고 그 확장 기능의 이름을 알려 줍니다.

2단계: 첫 PDF 렌더링하기

composer.json 옆에 01-hello.php라는 이름의 파일을 만듭니다. 이 완전한 프로그램을 붙여 넣으세요.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

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

echo "Wrote out/hello.pdf\n";

실행합니다.

php 01-hello.php

정확히 한 줄만 표시되어야 합니다.

Wrote out/hello.pdf

아무 PDF 뷰어에서나 out/hello.pdf를 엽니다. 굵은 제목 줄과 그 아래의 단락이 보이며, 대부분의 뷰어는 창 제목에 “Hello from NextPDF”를 표시합니다.

방금 일어난 일

스크립트를 위에서 아래로 하나씩 살펴봅시다.

require는 Composer 오토로더를 읽어 들이므로, Document 클래스가 해결됩니다.
@mkdir는 out/ 폴더를 만듭니다. 앞에 붙은 @는 폴더가 이미 존재할 때 스크립트를 조용하게 유지하므로, 다시 실행할 수 있습니다.
Document::createStandalone()은 새 문서를 반환합니다. 바로 이와 같은 짧은 명령줄 스크립트를 위해 만들어졌습니다.
setTitle()은 문서 제목을 설정하며, 뷰어는 이를 창 제목에 표시합니다.
addPage()는 빈 페이지 하나를 추가하고 커서를 왼쪽 위에 놓습니다.
setFont()은 글꼴 패밀리, 스타일, 포인트 단위의 크기를 선택합니다. 포인트는 인쇄에서 글꼴 크기의 표준 단위입니다. 'B'는 굵은 글씨를, ''는 일반 글씨를 의미합니다. helvetica라는 패밀리는 내장되어 있으므로, 글꼴 파일이 필요하지 않습니다.
cell()은 커서 위치에 텍스트 한 줄을 씁니다. 너비 0은 “오른쪽 여백까지 늘리기”를 의미합니다. newLine: true는 그 후 커서를 아래로 옮기며, 이는 Enter 키를 누르는 것과 같습니다.
save()는 완성된 PDF를 구성하여 디스크에 씁니다.

하나의 문서는 하나의 파일을 생성합니다. 두 번째 PDF가 필요할 때는, 이전 문서를 재사용하지 말고 새 문서를 만드세요.

3단계: 설정 검증하기

두 가지 간단한 점검으로, 이 설치가 스크립트 하나에 그치지 않고 계속 작동할 것임을 확인할 수 있습니다.

먼저, PHP에 포함된 확장 기능을 나열합니다.

php -m

목록에서 curl, gd, intl, mbstring, openssl, zlib를 찾아보세요. 엔진은 이 여섯 가지에 의존합니다. Composer가 1단계에서 이미 확인했으므로, 모두 표시되어야 합니다.

다음으로, 엔진 자체의 상태 점검을 실행합니다.

vendor/bin/nextpdf doctor

Windows에서는 대신 vendor\bin\nextpdf doctor를 호출합니다. 이 명령은 PHP 버전, 확장 기능, 임시 폴더, 구성을 검사합니다. 각 점검은 [OK], [WARN], 또는 [FAIL]을 출력하고, 그 뒤에 하나의 종합 판정을 표시합니다.

방금 일어난 일

먼저 Extensions 블록을 읽으세요. curl, gd, intl, mbstring, openssl, zlib라는 이름의 [OK] 줄 여섯 개가 있으면, 설치가 이후의 모든 튜토리얼에 대비된 상태입니다.

이 보고서에는 엔진 기능(capabilities)도 나열됩니다. 무료 Core 설치에서는, 상용 패키지에 속하는 기능이 그것을 제공하는 패키지 이름을 알리는 메시지와 함께 [FAIL]을 표시합니다. 이는 여기서 예상되는 동작이며, Core 설정에 문제가 없더라도 종합 판정이 UNHEALTHY로 바뀔 수 있습니다. 이 튜토리얼에서는 Extensions 블록이 중요한 신호입니다.

문제가 생겼을 때

먼저, 증상을 다음의 흔한 사례들과 대조해 보세요.

composer: command not found는 Composer가 없거나 PATH에 포함되어 있지 않다는 것을 의미합니다. getcomposer.org에서 설치한 다음, 1단계를 반복하세요.
Failed opening required '.../vendor/autoload.php'는 스크립트가 프로젝트 폴더 밖에서 실행되었거나, 설치가 완료되지 않았다는 것을 의미합니다. 1단계의 폴더로 이동하여 composer install을 실행하세요.
1단계 도중에 Composer가 멈추고 누락된 PHP 확장 기능의 이름을 알려 주면, php.ini에서 그 확장 기능을 활성화하세요. php -m으로 확인한 다음, 설치를 반복하세요.
doctor의 Extensions 블록에 있는 [FAIL] 줄은 누락된 PHP 확장 기능의 이름을 알려 줍니다. php.ini에서 활성화하고, php -m으로 확인한 다음, doctor를 다시 실행하세요. 상용 패키지 이름을 알리는 기능(capability) [FAIL] 줄은 Core 설치에서 예상되는 것이며, 여기서는 조치가 필요하지 않습니다.

그 밖의 경우에는 문제 해결 지식 베이스에서 시작하세요. 스크립트가 예외를 발생시키면, 오류 참조에서 해당 클래스를 찾아보세요. 초보자가 겪는 대부분의 오류는 일반 오류에 나와 있습니다.

다음 단계

이제 작동하는 설치 환경과 첫 렌더링 파일이 준비되었습니다. 페이지 크기, 내장 글꼴, 색상, 정렬을 제어하려면 텍스트, 글꼴, 페이지 기본 으로 계속하세요.