NextPDF Laravel 빠른 시작

한눈에 보기

이 튜토리얼에서는 컨트롤러에서 다운로드 가능한 PDF를 만듭니다. 그런 다음 같은 작업을 큐 작업으로 옮깁니다. 모든 스니펫은 패키지 테스트 스위트에서 검증한 동작과 일치합니다.

설치

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

개념 개요

세 가지 진입점으로 거의 모든 Laravel 사용 사례를 다룰 수 있습니다. 파사드는 가장 빠르게 시작하는 방법입니다. PdfResponse는 문서를 HTTP 응답으로 변환합니다. 큐 작업은 무거운 생성 작업을 요청 스레드 밖으로 옮겨 사용자가 이를 기다리지 않도록 합니다. 이 튜토리얼에서는 각 방법을 차례로 살펴봅니다. 오류 처리를 추가한 프로덕션급 버전은 /integrations/laravel/production-usage/에 있습니다.

코드 샘플 — 빠른 시작

1. 파사드

파사드는 호출할 때마다 컨테이너에서 새 문서 인스턴스를 가져옵니다. 컨테이너는 Laravel의 서비스 레지스트리입니다. 이 스니펫은 tests/Unit/Laravel/Facades/PdfTest.php에서 검증한 동작과 일치합니다.

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

2. 컨트롤러에서 다운로드 응답 반환

PdfResponse::download()는 Illuminate\Http\Response를 반환하며, 이 응답에는 Content-Type: application/pdf, attachment disposition, OWASP 보안 헤더가 포함됩니다. tests/Unit/Laravel/Http/PdfResponseTest.php는 상태 코드, 콘텐츠 유형, disposition 접두사, 헤더를 검증합니다.

<?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');
    }
}

브라우저 인라인 미리 보기를 사용하려면 download()를 inline()로 바꿉니다. 대용량 문서에는 streamInline() 또는 streamDownload()를 사용합니다. 이 메서드들은 결정론적인 64 KB 청크로 PDF를 전송합니다.

3. 큐 기반 생성

GeneratePdfJob는 큐 워커에서 PDF를 빌드하고 저장합니다. 빌더 클로저는 컨테이너에서 가져온 문서를 받아 구성된 문서를 반환합니다. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php는 작업이 정확한 출력 경로에 파일을 생성하는지 확인합니다.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

출력 경로는 반드시 .pdf로 끝나야 합니다. 작업은 쓰기 전에 워커에서 해당 경로를 검증합니다.

코드 샘플 — 프로덕션

프로덕션 버전에는 명시적인 오류 처리, 작업의 성공 및 실패 콜백, 형식화된 예외 전략이 추가됩니다. 전체 내용은 /integrations/laravel/production-usage/에 문서화되어 있습니다.

엣지 케이스 및 주의 사항

파사드는 해석될 때마다 다른 문서 인스턴스를 반환합니다. 논리적으로 별개인 문서 간에 Pdf::getFacadeRoot()를 캐시하지 마십시오.
어느 PdfResponse 팩토리에든 빈 파일 이름을 전달하면 기본값으로 document.pdf가 사용됩니다. 응답 테스트 스위트가 이 기본값을 검증합니다.
ASCII가 아닌 파일 이름에는 RFC 5987 filename*= 매개변수가 자동으로 적용됩니다. ASCII 이름에는 적용되지 않습니다.
GeneratePdfJob는 경로 순회, 스트림 래퍼, null 바이트, .pdf가 아닌 모든 확장자를 거부합니다. 워커에서 InvalidArgumentException을 발생시킵니다.

성능

단일 페이지 문서는 프런트매터에 명시된 페이지당 실행 시간 예산 안에서 충분히 생성됩니다. 생성 작업을 GeneratePdfJob로 옮기면 HTTP 요청에서 PDF 빌드 시간이 완전히 제거됩니다. 작업이 디스패치되면 요청은 곧바로 반환됩니다.

보안 참고 사항

PdfResponse 팩토리는 고정된 OWASP 헤더 세트를 적용합니다. 또한 다운로드 파일 이름을 정제합니다. 큐 작업은 출력 경로를 검증합니다. 자세한 위협 대응 범위는 /integrations/laravel/security-and-operations/에 있습니다.

적합성

이 튜토리얼에 적용되는 규범 표준은 없습니다. 모든 스니펫은 패키지 소스를 기준으로 검증됩니다. 또한 tests/ 아래의 해당 테스트를 기준으로도 검증됩니다.

상용 컨텍스트

서명된 출력과 PDF/A 출력은 nextpdf/premium에서 사용할 수 있습니다. 이는 선택적인 Enterprise 기능입니다. 여기에 문서화된 Core 패키지는 이를 도입하는 데 코드 변경이 필요하지 않습니다. https://nextpdf.dev/get-license/?intent=laravel-signing를 참조하십시오.

함께 보기

/integrations/laravel/install/ — 설치 및 설정 게시
/integrations/laravel/production-usage/ — DI로 연결되고 오류 처리가 적용된 컨트롤러와 작업
/integrations/laravel/configuration/ — 여기에서 사용한 설정 키
/integrations/laravel/overview/ — 아키텍처 및 바인딩 수명