NextPDF Laravel 패키지 설치

한눈에 보기

Composer로 nextpdf/laravel을 설치합니다. 자동 검색(auto-discovery)이 서비스 공급자를 자동으로 등록합니다. 그런 다음 구성 파일을 게시해 편집할 수 있게 합니다. 패키지는 선택적 NextPDF 확장을 자동으로 감지합니다.

설치

composer require nextpdf/laravel

이 패키지는 자체 composer.json에서 다음 제약 조건을 선언합니다:

요구 사항	제약 조건
PHP	`>=8.4 <9.0`
`laravel/framework`	`^12.0`
`nextpdf/core`	`^3.0 \|\| ^5.2`
`psr/http-client`	`^1.0`

패키지는 단일 PSR-4 매핑으로 자동 로드됩니다. NextPDF\Laravel\ 접두사는 src/Laravel/로 해석됩니다. 이는 PSR-4 접두사-기본 디렉터리 규칙(PSR-4 §3)을 따릅니다.

개념 개요

composer require 명령을 실행하면 Laravel 패키지 자동 검색이 이 패키지의 composer.json에서 extra.laravel 블록을 읽습니다. 그런 다음 공급자와 파사드 별칭을 자동으로 등록하므로 config/app.php을 직접 편집할 필요가 없습니다. 해당 블록은 다음과 같습니다:

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

Laravel 패키지 문서는 이 동작 방식을 설명합니다. extra.laravel.providers 배열은 서비스 공급자를 자동으로 등록하고, extra.laravel.aliases 배열은 파사드 별칭을 자동으로 등록합니다(Laravel 12 패키지 개발 가이드, https://laravel.com/docs/12.x/packages, 검색일 2026-05-18).

코드 예제 — 빠른 시작

구성 파일을 nextpdf-config 태그로 게시합니다. 이 태그 이름은 NextPdfServiceProvider::boot()에 정의되어 있습니다.

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

이렇게 하면 config/nextpdf.php가 애플리케이션에 작성됩니다. 또한 공급자는 register() 중에 nextpdf 키 아래로 패키지 기본 구성을 병합하므로, 게시하기 전에도 패키지가 동작합니다. 게시 작업은 애플리케이션에서 해당 파일을 편집할 수 있게 해줄 뿐입니다.

공급자가 감지되는지 확인합니다:

php artisan package:discover --ansi

코드 예제 — 프로덕션

재현 가능한 배포를 위해 제약 조건을 고정합니다. 공급자를 직접 등록할 때만 검색을 명시적으로 비활성화합니다:

{
  "extra": {
    "laravel": {
      "dont-discover": [
        "nextpdf/laravel"
      ]
    }
  }
}

검색을 비활성화한 경우 bootstrap/providers.php에서 공급자를 직접 등록합니다:

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

선택적 확장

이 패키지는 자체 composer.json의 suggest 아래에 선택적 보조 패키지를 나열합니다. 패키지는 런타임에 이를 감지합니다:

패키지	설치 시 효과	감지 지점
`nextpdf/artisan`	Chrome 팩토리 클래스가 있으면 Chrome CDP HTML 렌더러 구성이 문서 바인딩에 적용됩니다	`NextPdfServiceProvider::register()`가 Chrome 브라우저 팩토리 클래스를 확인합니다
`nextpdf/premium`	서명(PAdES B-B), PDF/A 아카이브, 전자 송장 계약 구현체가 기존 컨테이너 키를 통해 확인됩니다	첫 번째 컨테이너 확인 시 지연 방식으로 확인됩니다

확장도 같은 방식으로 설치합니다:

composer require nextpdf/artisan

추가 연결 작업은 필요 없습니다. 공급자는 다음 등록 시 해당 확장을 감지합니다.

엣지 케이스 및 유의 사항

게시 작업은 멱등적입니다. 기존 config/nextpdf.php를 덮어쓰지 않습니다. 의도적으로 덮어쓰려면 --force를 추가합니다.
공급자는 지연되므로, 패키지 감지 확인에는 php artisan package:discover만으로 충분합니다. 바인딩 자체는 첫 번째 확인 전까지 나타나지 않습니다.
이 패키지는 nextpdf/core를 ^3.0 및 ^5.2 메이저 라인 모두에서 지원합니다. 코어 제약 조건은 애플리케이션이 고정한 라인에 맞춥니다. Laravel 어댑터 표면은 두 라인에서 동일합니다.
README 배지와 composer.json은 Apache-2.0으로 일치합니다. 이 패키지는 LGPL-3.0-or-later에서 라이선스가 변경되었습니다. 마이그레이션 이전에 태그된 버전은 이전 라이선스로 유지됩니다(CHANGELOG.md 참조).

성능

패키지 nextpdf/core 확인이 composer require 비용의 대부분을 차지합니다. 모든 바인딩이 지연 클로저이므로, 공급자 등록은 측정 가능한 부팅 비용을 추가하지 않습니다. 첫 번째 확인 시 발생하는 생성 비용은 /integrations/laravel/boot-and-discovery/.에 문서화되어 있습니다.

보안 참고 사항

공식 Packagist 패키지 nextpdf/laravel에서 설치합니다. 패키지는 SPDX REUSE 헤더와 Apache-2.0 NOTICE 파일을 함께 제공합니다. 배포된 워커가 검증된 종속성 트리를 확인할 수 있도록 composer.json에서 제약 조건을 고정하고 composer.lock을 커밋합니다.

적합성

주장	출처	절	reference_id (참조 ID)
PSR-4 접두사가 기본 디렉터리에 매핑됨	PSR-4 Autoloader (자동 로더)	§3

Laravel 자동 검색 키 이름은 공식 Laravel 12 패키지 개발 문서(https://laravel.com/docs/12.x/packages, 검색일 2026-05-18)와 대조해 확인되었습니다.

상업적 컨텍스트

nextpdf/premium은 서명, PDF/A, 전자 송장 구현체를 추가합니다. 이는 선택적 Enterprise 기능입니다. 여기에 문서화된 Core 패키지는 이를 채택하는 데 코드 변경이 필요하지 않습니다. <https://nextpdf.dev/get-license/? 참조 intent=laravel-signing>.

참고 항목

/integrations/laravel/overview/ — 패키지 아키텍처 및 바인딩 표
/integrations/laravel/quickstart/ — 첫 번째 실행 가능한 컨트롤러
/integrations/laravel/configuration/ — 모든 구성 키 설명
/integrations/laravel/boot-and-discovery/ — 검색 내부 동작 및 바인딩 수명