HTML을 PDF로, 쉬운 방법

지금까지 이 트랙에서는 한 번에 하나의 호출로 페이지를 만들어 왔습니다. 많은 문서는 웹 페이지에 쓰이는 태그 기반 텍스트 형식인 마크업으로 표현하는 편이 더 빠릅니다. 이 튜토리얼에서는 NextPDF에 Hypertext Markup Language(HTML)을 건네주면, 엔진이 대신 페이지를 그려 줍니다.

만들게 될 결과물

하나의 HTML 문자열에서 렌더링되는 한 페이지짜리 보고서입니다. 색상이 적용된 제목, 짧은 단락, 그리고 합계 행이 있는 표로 구성됩니다. 마크업의 표시 방식을 제어하는 규칙 언어인 Cascading Style Sheets(CSS)로 스타일을 지정합니다. 앞선 튜토리얼에서는 메서드 호출을 연결하는 플루언트 Application Programming Interface(API)를 사용했습니다. 여기서는 대신 레이아웃을 마크업으로 기술하고, 동일한 엔진이 이를 렌더링합니다.

1단계: HTML에서 스타일이 적용된 보고서 렌더링하기

프로젝트 폴더에서 vendor 옆에 01-html.php라는 파일을 만듭니다. 아래의 전체 스크립트를 붙여 넣습니다.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

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

echo "Wrote out/reading-report.pdf\n";

프로젝트 폴더에서 스크립트를 실행합니다.

php 01-html.php

출력으로 한 줄이 표시됩니다.

Wrote out/reading-report.pdf

out/reading-report.pdf를 아무 Portable Document Format(PDF) 뷰어에서나 엽니다. 제목은 짙은 파란색이고, 표의 머리글 행도 같은 색으로 채워져 있습니다.

방금 일어난 일

@mkdir(__DIR__ . '/out');는 출력 폴더를 만듭니다. @ 기호는 폴더가 이미 있을 때 발생하는 경고를 숨기므로, 반복 실행해도 조용히 동작합니다.
Document::createStandalone(), setTitle(), addPage()는 앞선 튜토리얼과 정확히 동일하게 동작합니다. 마크업으로 전환해도 문서 설정 방식은 전혀 바뀌지 않습니다.
writeHtml()는 문자열을 위에서 아래로 한 번 읽으며 각 요소를 현재 위치에 그립니다. 제목과 단락은 스타일이 적용된 텍스트가 됩니다. 표는 테두리가 있는 셀로 이루어진, 크기가 측정된 행이 됩니다.
인라인 style 속성이 CSS를 담고 있습니다. 엔진은 color, background-color, text-align, width 같은 일반적인 속성을 이해합니다.
브라우저나 추가 소프트웨어는 전혀 필요하지 않습니다. 파이프라인은 엔진 내부의 순수 PHP이므로, Composer 설치가 동작하는 곳이라면 어디서나 스크립트가 실행됩니다.

엔진은 브라우저가 받아들이는 모든 것이 아니라, HTML과 CSS의 실용적인 하위 집합을 지원합니다. 그 하위 집합을 벗어나는 것은 오류를 일으키지 않고 조용히 건너뜁니다. CSS 지원 매트릭스에 정확히 무엇이 지원되는지 기록되어 있습니다. 이 파이프라인을 더 깊이 살펴보려면 HTML을 PDF 페이지로 렌더링하기를 참고하세요.

HTML을 쓸 때와 플루언트 API를 쓸 때

두 방식 모두 동일한 엔진에서 실행되므로, 문서에 맞는 쪽을 선택하면 됩니다.

문서가 웹 페이지처럼 읽히는 경우, 즉 제목, 단락, 목록, 표로 이루어진 경우에는 writeHtml()을 선택합니다. 마크업은 작성이 더 빠르고 팀원이 편집하기도 더 쉽습니다.
고정 위치나 정밀하게 측정된 셀처럼 정확한 배치가 필요한 경우에는 플루언트 API를 선택합니다. 마크업은 흐름을, 플루언트 호출은 제어를 제공합니다.
속성에 의존하기 전에 CSS 지원 매트릭스를 확인하세요. 스타일이 지원되지 않는 경우에는 그 부분을 대신 플루언트 호출로 구성합니다.

안전 경계

실제 HTML은 폼이나 데이터베이스 등 코드 외부에서 오는 경우가 많습니다. 이를 신뢰할 수 없는 입력으로 취급하고, 렌더링하기 전에 검증하거나 정제해야 합니다. 기본적으로 내장 파이프라인은 어떤 스크립트도 실행하지 않고 원격 리소스도 가져오지 않습니다. 이 기본값 덕분에 마크업이 그렇지 않더라도 렌더러는 보수적으로 유지됩니다. 브라우저 수준의 렌더링 옵션이 필요하다면 경로 선택하기를 참고하세요.

문제가 발생했다면

Failed to open stream: No such file or directory는 대개 스크립트가 vendor/autoload.php를 찾지 못한다는 뜻입니다. Composer를 실행했던 폴더에서 스크립트를 실행하세요.
스타일이 적용되지 않는 경우는 대개 지원되는 하위 집합을 벗어난 속성 때문입니다. 엔진은 지원하지 않는 것을 실패로 처리하지 않고 건너뜁니다. 마크업을 CSS 지원 매트릭스와 대조해 보세요.
렌더링 중 발생하는 예외는 정확한 문제를 알려 줍니다. 렌더링 및 입출력 오류 레퍼런스에서 찾아보세요.

그 밖의 문제는 문제 해결 가이드에서 시작하세요.

다음 단계

이제 호출 단위로도, 마크업으로도 문서를 만들 수 있습니다. 다음으로 갈 곳으로 이 트랙을 마무리하세요. 이 페이지는 트랙을 마친 후 사용하게 될 쿡북, 레퍼런스, 가이드를 정리해 줍니다.