첫 번째 PDF

한눈에 보기

이 튜토리얼에서는 두 개의 PDF 파일을 생성합니다. 첫 번째 파일에서는 플루언트 코어 API로 텍스트를 직접 작성합니다. 두 번째 파일에서는 HyperText Markup Language(HTML)와 Cascading Style Sheets(CSS) 조각을 페이지에 렌더링합니다. 끝까지 따라 하면 실제 문서에 맞게 응용할 수 있는 실행 가능한 스크립트가 준비됩니다. 또한 프레임워크 및 서버 변형을 어디에서 찾을 수 있는지도 알게 됩니다.

두 방식 모두 동일한 엔진에서 실행됩니다. 따라서 여기서 배운 내용은 모든 배포판에 그대로 적용할 수 있습니다.

아래 다이어그램은 두 가지 작성 방식과 이를 재사용하는 세 가지 배포 영역을 보여 줍니다.

From your code to a PDF file

시작하기 전에

두 가지가 필요합니다. 설치된 코어 엔진, 그리고 PHP 스크립트를 실행할 수 있는 환경입니다.

1. PHP 8.4가 활성 런타임인지 확인합니다.

   php --version

2. 코어 엔진이 아직 설치되어 있지 않다면 프로젝트에 설치합니다.

   composer require nextpdf/core

3. 프로젝트 루트에 first-pdf.php라는 작업 파일을 만듭니다.

표준 14개 글꼴은 설정 없이 동작합니다

기본 본문 서체는 ISO 32000-2에 명시된 표준 14개 Type 1 글꼴 중 하나로 결정됩니다. 따라서 첫 번째 문서에는 글꼴 파일이 필요하지 않습니다. 사용자 지정 글꼴은 디자인상 필요해졌을 때 나중에 등록하고 포함하면 됩니다.

PHP에서 PDF 생성하기

플루언트 API부터 시작합니다. Document::createStandalone()은 바로 사용할 수 있는 문서를 반환합니다. 페이지를 추가하고, 글꼴을 설정하고, 셀을 작성한 다음 저장합니다. 각 작성 메서드는 문서를 반환하므로 호출 흐름을 위에서 아래로 읽을 수 있습니다.

1. 이 코드를 first-pdf.php에 넣습니다. 이 스크립트는 엄격한 타입을 선언하고, 오토로더를 로드한 다음, 한 페이지짜리 문서를 만듭니다.

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('My first NextPDF document');
   $document->addPage();
   
   $document->setFont('helvetica', 'B', 24);
   $document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
   
   $document->setFont('helvetica', '', 12);
   $document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);
   
   $document->save(__DIR__ . '/first-pdf.pdf');
   
   echo "Wrote first-pdf.pdf\n";

2. 스크립트를 실행합니다.

   php first-pdf.php

3. 출력을 확인합니다. 표준 출력에 다음 줄이 표시되고, 스크립트와 같은 디렉터리에 first-pdf.pdf라는 새 파일이 생성되어야 합니다.

   Wrote first-pdf.pdf

이제 유효한 PDF 2.0 파일을 생성했습니다. 어떤 뷰어에서든 열면 제목과 그 아래 줄이 보입니다.

save와 output 비교

save()는 문서를 파일 경로에 씁니다. 대신 바이트를 브라우저로 스트리밍하려면 output()를 호출합니다. 바이트를 메모리에 담으려면 getPdfData()를 호출합니다. 문서 인스턴스는 일회용입니다. 하나를 작성한 후에는 재사용하지 말고, 다음 문서에는 새 인스턴스를 만들어야 합니다.

HTML을 PDF로 렌더링하기

셀을 작성하면 정밀하게 제어할 수 있습니다. 하지만 대부분의 문서는 HTML과 CSS로 표현하는 편이 더 빠릅니다. 코어 엔진에는 순수 PHP HTML 파이프라인이 포함되어 있습니다. 이 파이프라인의 writeHtml() 메서드는 조각을 현재 페이지에 렌더링합니다. 브라우저나 외부 서비스를 사용하지 않습니다.

1. HTML 조각을 렌더링하는 두 번째 파일 html-pdf.php를 만듭니다.

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('HTML to PDF');
   $document->addPage();
   
   $html = <<<'HTML'
   <h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
   <p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
   <ul>
       <li>Headings, paragraphs, and lists</li>
       <li>Inline <strong>bold</strong> and <em>italic</em></li>
       <li>Inline styles such as color and font-size</li>
   </ul>
   HTML;
   
   $document->writeHtml($html);
   
   $document->save(__DIR__ . '/html-pdf.pdf');
   
   echo "Wrote html-pdf.pdf\n";

2. 실행합니다.

   php html-pdf.php

3. 출력 줄과 새 파일을 확인합니다.

   Wrote html-pdf.pdf

HTML 입력은 신뢰할 수 없는 것으로 취급해야 합니다

HTML이 사용자, 폼 또는 임의의 외부 소스에서 오는 경우, writeHtml()에 전달하기 전에 검증하고 정제해야 합니다. HTML을 PDF 페이지로 렌더링하기 레시피에서 전체 보안 태세와 스트리밍 모델을 다룹니다.

엔진은 HTML과 CSS의 지원되는 하위 집합을 렌더링합니다. 속성에 의존하기 전에 CSS 지원 매트릭스와 대조하여 확인해야 합니다. 레이아웃에 브라우저 수준의 완전한 충실도가 필요한 경우(예: flexbox, grid 또는 웹 글꼴) Artisan 렌더러를 설치하고 대신 writeHtmlChrome()를 호출해야 합니다. 이 메서드는 텍스트를 선택 가능한 상태로 유지합니다.

프레임워크 컨트롤러에서

애플리케이션이 이미 프레임워크 위에서 실행 중이거나 서버로 동작하고 있을 수 있습니다. 동일한 두 호출을 해당 환경으로 옮겨 사용할 수 있습니다. 엔진은 그대로이고 연결 방식만 바뀝니다.

Laravel

Laravel의 Pdf 파사드는 호출할 때마다 새 문서를 생성합니다. PdfResponse는 문서를 다운로드 응답으로 변환합니다.

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

자세한 내용은 Laravel 빠른 시작에서 확인할 수 있습니다.

Symfony

이 번들은 PdfFactory 서비스를 노출합니다. 컨트롤러에서 NextPDF\Symfony\Service\PdfFactory를 타입 힌트로 지정하고, 같은 방식으로 문서를 만든 다음 HTTP 응답으로 반환합니다. Symfony 빠른 시작에서 확인할 수 있습니다.

서버 (REST)

NextPDF Server가 실행 중인 상태에서 순서가 지정된 작업 배열을 POST하면 서버가 PDF 바이트를 반환합니다.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

성공적인 200 응답의 본문은 PDF입니다. Connect 빠른 시작에서 확인할 수 있습니다.

다음 단계

이제 세 가지 방법으로 PDF를 생성했습니다. 각 방법에서 다음으로 이어서 볼 내용은 다음과 같습니다.

HTML 을 PDF 페이지로 렌더링하기 전체 HTML 레시피로, 지원되는 요소, 스트리밍 모델, 보안 태세를 다룹니다.

경로 선택하기 코어, 프레임워크, 서버 중 무엇을 선택할지, 그리고 어떤 HTML 렌더러를 사용할지 결정합니다.

코어 엔진 레퍼런스 모든 Document 메서드, 매개변수, 반환값을 다룹니다.

쿡북 스타일링, 표, 페이지 매김 등을 위한 작업 중심 레시피입니다.