NextPDF Laravel 통합 개요

한눈에 보기

nextpdf/laravel 패키지는 NextPDF PDF 엔진을 Laravel 12 애플리케이션에 연결하고 컨테이너 바인딩을 대신 등록합니다. 이 패키지는 Pdf 파사드, PdfResponse HTTP 헬퍼, 큐에 등록할 수 있는 GeneratePdfJob을 함께 제공합니다. Laravel이 이 패키지를 자동으로 검색하므로 직접 등록하지 않아도 됩니다.

설치

composer require nextpdf/laravel

Composer 제약 조건은 nextpdf/core: ^3.0 || ^5.2입니다. 또한 이 패키지는 laravel/framework: ^12.0 및 php: >=8.4 <9.0도 요구합니다. 구성 게시 및 선택적 확장을 포함한 전체 절차는 /integrations/laravel/install/을 참조하십시오.

개념 개요

이 패키지는 Laravel 서비스 컨테이너와 프레임워크에 종속되지 않는 NextPDF 코어 사이의 좁은 접점에 위치합니다. PDF 생성을 다시 구현하지 않습니다. 대신 코어 NextPDF\Core\Document 모델을 Laravel의 생명 주기, 구성, 큐잉, HTTP 계층에 맞게 조정합니다.

아래 다이어그램은 요청이 애플리케이션 코드에서 시작해 패키지를 거쳐 공유 코어 레지스트리로 흐르는 과정을 보여 줍니다.

NextPDF Laravel request and render flow

자동 로드 매핑은 단일 PSR-4 항목으로 구성됩니다. PSR-4는 자동 로드를 위한 PHP 표준 권장 사항이며, 그 접두사 NextPDF\Laravel\는 src/Laravel/에 매핑됩니다. PSR-4에서는 네임스페이스 접두사가 기준 디렉터리에 대응하고, 나머지 클래스 이름은 해당 디렉터리 아래의 파일 경로에 매핑됩니다(PSR-4 §3). 이 접두사 아래에는 네 개의 프로덕션 클래스가 있습니다:

NextPDF\Laravel\NextPdfServiceProvider — 바인딩을 등록하고 구성을 게시합니다.
NextPDF\Laravel\Facades\Pdf — 컨테이너에서 새 문서를 해석하는 정적 프록시입니다.
NextPDF\Laravel\Http\PdfResponse — 고정된 보안 헤더 집합과 함께 인라인, 다운로드, 스트리밍 PDF 응답을 생성하는 팩토리입니다.
NextPDF\Laravel\Jobs\GeneratePdfJob — 워커에서 PDF를 빌드하고 저장하는 큐에 등록할 수 있는 작업입니다.

서비스 공급자는 DeferrableProvider를 구현하므로, 노출된 항목 중 하나를 해석할 때만 바인딩을 등록합니다. 이러한 지연 처리는 프레임워크 부팅 경로를 가볍게 유지합니다. 공급자의 provides() 메서드는 지연 항목을 나열하며, 컨테이너는 이 목록을 읽어 각 키를 다시 공급자에 매핑합니다.

해석은 컨테이너 계약을 따릅니다. 바인딩이 존재하면 식별자를 해석할 때 등록된 항목이 반환됩니다. PSR-11은 컨테이너 상호 운용성을 위한 PHP 표준 권장 사항이며, 동일한 식별자로 get()를 연속해서 두 번 호출해도 바인딩 전략에 따라 서로 다른 값을 반환할 수 있다고 명시합니다(PSR-11 §1.1.2). NextPDF는 의도적으로 이 동작에 의존합니다. 레지스트리는 싱글턴이므로 해석할 때마다 동일한 인스턴스를 반환하고, 문서는 팩토리에 바인딩되므로 해석할 때마다 새 인스턴스를 반환합니다. 전체 바인딩 수명 표는 /integrations/laravel/boot-and-discovery/를 참조하십시오.

이 아키텍처는 Octane, RoadRunner, Swoole과 같은 장기 실행 워커를 대상으로 합니다. 글꼴 레지스트리는 프로세스 수명 동안 유지되는 싱글턴입니다. 패키지는 이를 한 번 워밍한 뒤 잠그므로 어떤 요청도 공유 글꼴 상태를 변경할 수 없습니다. 이미지 레지스트리는 크기가 제한된 LRU(least-recently-used) 캐시를 갖춘 프로세스 수명 싱글턴입니다. 패키지는 항상 DocumentFactory에서 문서를 새로 생성하므로 요청별 가변 상태가 요청 간에 누출되지 않습니다.

API 표면

클래스	공개 진입점	반환 값	용도
`NextPdfServiceProvider`	`register()`, `boot()`, `provides()`	`void` / `array`	컨테이너 바인딩, 구성 게시, 지연 항목 목록
`Facades\Pdf`	정적 프록시(`addPage()`, `cell()`, `save()`, …)	`static` / mixed	각 호출에서 `PdfDocumentInterface`를 해석
`Http\PdfResponse`	`inline()`, `download()`, `streamInline()`, `streamDownload()`	`Response` / `StreamedResponse`	OWASP 헤더를 포함한 HTTP 응답
`Jobs\GeneratePdfJob`	`dispatch()`, `handle()`, `then()`, `catch()`, `failed()`	`PendingDispatch` / `void` / `self`	큐 기반 PDF 생성

공급자가 바인딩하는 컨테이너 키:

키	수명	해석 대상
`NextPDF\Contracts\FontRegistryInterface` (별칭 `FontRegistry`)	싱글턴, 잠김	`NextPDF\Typography\FontRegistry`
`NextPDF\Graphics\ImageRegistry`	싱글턴, LRU 제한	`ImageRegistry`
`NextPDF\Contracts\DocumentFactoryInterface` (별칭 `DocumentFactory`)	싱글턴	`NextPDF\Core\DocumentFactory`
`Psr\Http\Client\ClientInterface`	싱글턴	`SecurityAwareHttpClient`, 래핑 대상 `CurlHttpClient`
`NextPDF\Security\Timestamp\TsaClient`	스코프	`TsaClient` 또는 `null`(TSA URL이 없을 때)
`NextPDF\Contracts\SignerInterface`	팩토리	`DigitalSigner` 또는 `null`(서명이 비활성화된 경우)
`NextPDF\Contracts\PdfDocumentInterface` (별칭 `nextpdf`)	팩토리	`NextPDF\Core\Document`
`NextPDF\Contracts\EInvoice\{Embedder,Validator,Profile,SchematronRunner}Interface`	팩토리	오직 `nextpdf/premium`이 설치된 경우에만 해석됨

코드 샘플 — 빠른 시작

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

컨트롤러 범위에서 실행할 수 있는 예제는 /integrations/laravel/quickstart/를 참조하십시오.

코드 샘플 — 프로덕션

프로덕션 패턴은 문서 계약을 파사드가 아니라 컨테이너에서 해석하므로 호출 지점이 명시적이고 테스트하기 쉬워집니다. 의존성 주입(DI)과 오류 처리를 포함한 전체 컨트롤러는 /integrations/laravel/production-usage/를 참조하십시오.

<?php

declare(strict_types=1);

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

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Invoice', newLine: true);

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

엣지 케이스 및 주의 사항

공급자가 지연 처리되므로 관련 없는 컨테이너 키를 해석해도 NextPDF가 부팅되지 않습니다. 바인딩은 provides() 항목 중 하나를 요청할 때만 사용할 수 있게 됩니다.
SignerInterface와 TsaClient는 서명이나 타임스탬프 기관을 구성하지 않은 경우 설계상 null로 해석됩니다. 코드에서는 결과를 null 검사해야 하며, 인스턴스가 존재한다고 가정해서는 안 됩니다.
e-인보이스 계약 바인딩은 항상 등록되지만, nextpdf/premium이 설치된 경우에만 존재하는 Premium 구현체로 해석됩니다. Premium 없이 이를 해석하면 class-not-found 오류가 발생하며, 이 오류는 부팅 시점이 아니라 처음 해석할 때 나타납니다.
파사드는 해석할 때마다 새 문서를 반환합니다. 동일한 요청 내에서 Pdf:: 정적 호출을 두 번 하고 그 사이에 Pdf::clearResolvedInstances()를 호출하는 경우를 생각해 보십시오. 두 호출은 서로 다른 문서에서 작동합니다.

성능

공급자 등록은 O(1) 시간에 실행됩니다. 공급자는 클로저를 바인딩하고 비용이 큰 객체를 생성하지 않으므로, 생성 비용은 처음 해석할 때까지 지연됩니다. 글꼴 레지스트리 워밍은 O(f) 시간에 실행되며, 여기서 f는 사전 로드된 글꼴 파일의 개수이고 워커 프로세스당 한 번 실행됩니다. 이러한 타이밍은 장기 실행 워커에서 첫 요청 지연 시간을 분산시킵니다. 이 개요의 페이지별 메모리 예산은 프런트매터 필드 performance_budget에 기록되어 있습니다.

보안 참고 사항

PdfResponse는 Open Worldwide Application Security Project(OWASP)의 고정 헤더 집합을 적용합니다. 헤더는 X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: default-src 'none', X-Robots-Tag, 그리고 Referrer-Policy: no-referrer입니다. GeneratePdfJob는 워커 측에서 출력 경로를 검증하며, 이 검사는 변조된 직렬화 페이로드로 인한 위험을 완화합니다. 전체 위협 모델 및 배포 구성은 /integrations/laravel/security-and-operations/를 참조하십시오.

적합성

주장	출처	조항	참조 ID(reference_id)
컨테이너 해석 / 수명 의미 체계	PSR-11 컨테이너	§1.1.2
PSR-4 자동 로드 접두사 매핑	PSR-4 자동 로더	§3

상업적 맥락

nextpdf/premium이 설치되면 동일한 공급자가 디지털 서명(PAdES B-B), PDF/A 아카이빙, e-인보이스 계약 바인딩 등 더 많은 기능을 노출합니다. 공급자는 이러한 기능을 동일한 컨테이너 키를 통해 노출하므로, 여기에 설명된 Core 패키지는 이러한 기능을 채택할 때 코드 변경을 요구하지 않습니다. 자세한 내용은 다음을 참조하십시오. https://nextpdf.dev/get-license/?intent=laravel-signing.

참고 항목

/integrations/laravel/install/ — 설치 절차 및 선택적 확장
/integrations/laravel/quickstart/ — 실행 가능한 컨트롤러 예제
/integrations/laravel/configuration/ — 모든 구성 키가 검증된 config/nextpdf.php
/integrations/laravel/production-usage/ — DI로 연결된 컨트롤러, 오류 처리, 큐잉
/integrations/laravel/boot-and-discovery/ — 자동 검색 및 바인딩 수명
/integrations/laravel/security-and-operations/ — 위협 모델 및 배포 구성