NextPDF Laravel 통합

한눈에 보기

이 가이드는 NextPDF를 Laravel 12 애플리케이션에 연결하는 과정을 설명합니다. 패키지 설치, Laravel의 자동 검색, 구성 게시, 컨테이너 바인딩 해석, HTTP 응답 반환, 큐 작업 실행이라는 여섯 단계를 차례로 다룹니다. 각 단계는 해당 영역의 심화 참고 문서로 이어집니다.

설치

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

부트/자동 검색

Laravel은 패키지의 composer.jsonextra.laravel 블록에서 서비스 프로바이더와 파사드 별칭을 자동으로 검색합니다. config/app.php를 편집할 필요가 없습니다. 오토로드 맵은 단일 PSR-4 항목입니다. NextPDF\Laravel\ 접두사는 PSR-4 접두사-기본 디렉터리 규칙(PSR-4 §3)에 따라 src/Laravel/로 해석됩니다. 프로바이더는 지연(deferred) 로드되며, provides() 항목 중 하나가 처음 해석될 때 부트됩니다. 자동 검색의 전체 내부 동작은 /integrations/laravel/boot-and-discovery/ 문서에서 다룹니다.

컨테이너 바인딩

컨테이너에서 문서 계약(contract)을 해석합니다. 바인딩된 식별자는 등록된 항목으로 해석됩니다(PSR-11 §1.1.2). 문서 바인딩은 팩토리이므로 해석할 때마다 새 문서가 반환됩니다. 글꼴 및 이미지 레지스트리는 싱글톤이므로 해석할 때마다 동일한 공유 인스턴스를 반환합니다. 전체 바인딩 수명 표는 /integrations/laravel/overview/ 및 /integrations/laravel/boot-and-discovery/ 문서에서 확인할 수 있습니다.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

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

구성 게시

php artisan vendor:publish --tag=nextpdf-config

이 명령은 config/nextpdf.php를 생성합니다. 모든 키, 해당 환경 변수, 기본값은 /integrations/laravel/configuration/ 문서에 문서화되어 있습니다.

서비스 프로바이더/번들 스모크 테스트

이 패키지는 프로바이더를 처음부터 끝까지 검증하는 Testbench 기반 테스트 스위트를 제공합니다. 다음은 이 패키지를 사용하는 애플리케이션에 추가할 수 있는 최소 스모크 테스트입니다.

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

이 두 검증은 패키지 자체의 EInvoiceServiceProviderIntegrationTest에 있는 일회성 적합성 검사를 반영합니다. 이 검사는 문서가 팩토리로 바인딩되고 글꼴 레지스트리가 잠긴 싱글톤인지 확인합니다.

공개 API 진입점

진입점	용도	참고
`NextPDF\Laravel\Facades\Pdf`	새 문서에 대한 정적 프록시	/integrations/laravel/quickstart/（빠른 시작）
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	컨테이너에서 해석된 문서	/integrations/laravel/production-usage/（프로덕션 사용）
`NextPDF\Laravel\Http\PdfResponse`	인라인 / 다운로드 / 스트리밍 HTTP 응답	/integrations/laravel/security-and-operations/（보안 및 운영）
`NextPDF\Laravel\Jobs\GeneratePdfJob`	큐를 통한 생성	/integrations/laravel/production-usage/（프로덕션 사용）

코드 예제 — 프로덕션

의존성 주입으로 연결하고 오류 처리를 적용한 컨트롤러는 /integrations/laravel/production-usage/ 문서에 전체 내용이 문서화되어 있습니다. 성공 및 실패 콜백을 포함한 큐 작업도 동일한 문서에서 다룹니다.

엣지 케이스 & 주의 사항

해석할 대상은 PdfDocumentInterface이며, 구체 클래스인 Document가 아닙니다. 이렇게 해야 바인딩을 테스트 가능하고 교체 가능하게 유지할 수 있습니다.
SignerInterface와 TsaClient는 구성되기 전까지 null로 해석됩니다. 항상 null 검사를 수행해야 합니다.
e-인보이스 계약에는 nextpdf/premium이 필요합니다. 해당 계약은 바인딩되어 있지만, 이 패키지 없이는 처음 해석할 때 오류가 발생합니다.

성능

프로바이더가 지연 로드되므로 전체 연결 흐름은 부트 비용을 추가하지 않습니다. 최초 해석 시 발생하는 생성 비용과 글꼴 워밍업 비용은 /integrations/laravel/boot-and-discovery/ 문서에서 다룹니다.

보안 참고 사항

PdfResponse는 고정된 OWASP 헤더 집합을 적용합니다. GeneratePdfJob은 워커에서 출력 경로를 검증합니다. 위협 모델은 /integrations/laravel/security-and-operations/ 문서에서 다룹니다.

적합성

주장	출처	조항	참고 ID
바인딩된 식별자는 등록된 항목으로 해석됩니다	PSR-11 컨테이너	§1.1.2
PSR-4 접두사가 기본 디렉터리로 매핑됩니다	PSR-4 자동 로더	§3

상용 컨텍스트

서명, PDF/A, e-인보이스 계약은 nextpdf/premium이 설치되어 있을 때 동일한 프로바이더를 통해 통합됩니다. 이는 선택적 Enterprise 기능입니다. 여기에 문서화된 Core 패키지에서는 이를 도입할 때 코드 변경이 필요하지 않습니다. 자세한 내용은 https://nextpdf.dev/get-license/?intent=laravel-signing에서 확인할 수 있습니다.

참고 자료

/integrations/laravel/overview/ — 아키텍처 및 바인딩 표
/integrations/laravel/install/ — 설치 및 선택적 확장
/integrations/laravel/quickstart/ — 처음 실행할 수 있는 예제
/integrations/laravel/production-usage/ — DI, 오류 처리, 큐
/integrations/laravel/boot-and-discovery/ — 검색 및 수명 주기