NextPDF Laravel 부팅과 자동 검색

한눈에 보기

Laravel은 패키지의 composer.json에서 NextPdfServiceProvider를 자동으로 검색합니다. 이 프로바이더는 지연 컨테이너 바인딩을 등록하며, 콘솔 컨텍스트에서는 구성 파일을 게시합니다. 이 페이지에서는 검색 방식과 각 바인딩의 수명을 단계별로 살펴봅니다.

설치

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

Laravel 자동 검색의 작동 방식

패키지는 자체 composer.json 안의 extra.laravel 블록에서 프로바이더와 파사드 별칭을 선언합니다:

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

다음과 같이 composer require를 실행하면 Laravel이 이 블록을 읽고 프로바이더와 별칭을 등록합니다. config/app.php나 bootstrap/providers.php를 직접 편집할 필요는 없습니다. extra.laravel.providers 배열은 서비스 프로바이더를 자동으로 등록하고, extra.laravel.aliases는 파사드 별칭을 자동으로 등록합니다(Laravel 12 패키지 개발 가이드, https://laravel.com/docs/12.x/packages, 검색일 2026-05-18).

부팅 시퀀스

NextPdfServiceProvider는 DeferrableProvider와 표준 register() / boot() 수명 주기를 모두 구현합니다.

**register()**는 패키지 구성을 nextpdf 키 아래에 병합합니다. 그런 다음 글꼴 레지스트리, 이미지 레지스트리, 문서 팩토리, PSR-18 HTTP 클라이언트, 타임스탬프 클라이언트, 서명자, 문서, 전자 송장 계약 등 컨테이너 항목을 바인딩합니다. 모든 바인딩은 클로저이므로 이 단계에서는 무거운 객체가 생성되지 않습니다.
**boot()**는 mbstring 및 zlib PHP 확장이 로드되었는지 확인합니다. 게시 가능한 구성을 nextpdf-config 태그 아래에 등록하며, 이는 runningInConsole()이 true일 때만 수행됩니다.

이 프로바이더는 지연되므로 register()는 provides()가 반환하는 항목 중 하나가 확인(resolve)될 때만 실행됩니다. 관련 없는 컨테이너 키를 확인해도 NextPDF가 부팅되지는 않습니다.

컨테이너 바인딩 및 수명

PSR-11은 동일한 식별자로 get()을 연속 호출했을 때 두 호출이 바인딩 전략에 따라 서로 다른 값을 반환하는 것을 허용합니다(PSR-11 §1.1.2). 이 프로바이더는 의도적으로 이 동작에 의존합니다:

바인딩 키	수명	참고
`FontRegistryInterface` (+ `FontRegistry` 별칭)	싱글톤, 워밍업 후 잠김	글꼴은 `preload_fonts`에서 워밍업되고 잠긴 상태라 어떤 요청도 변경할 수 없습니다.
`ImageRegistry`	싱글톤	용량이 `image_cache_mb`로 제한되는 LRU 캐시이며, 잠금은 없습니다.
`DocumentFactoryInterface` (+ `DocumentFactory` 별칭)	싱글톤	상태 비저장이며, 두 레지스트리를 공유합니다.
`Psr\Http\Client\ClientInterface`	싱글톤	curl 클라이언트를 래핑하는 요청 위조 인식 클라이언트이며, 빌드 소스: `tsa.*`
`TsaClient`	스코프 지정	`tsa.url`이 비어 있으면 `null`입니다
`SignerInterface`	팩토리	서명이 비활성화되었거나 인증서가 비어 있으면 `null`입니다
`PdfDocumentInterface` (+ `nextpdf` 별칭)	팩토리	확인할 때마다 새 `NextPDF\Core\Document`를 생성하고 기본 메타데이터를 적용합니다
`EmbedderInterface`, `ValidatorInterface`, `ProfileInterface`, `SchematronRunnerInterface`	팩토리	Premium 구체 구현으로 확인되며, `nextpdf/premium` 패키지 없이 처음 확인하면 오류가 발생합니다

문서 바인딩은 새 문서마다 defaults.creator, defaults.language, 그리고 (비어 있지 않을 때) defaults.author를 적용합니다. pdfa가 null이 아니면 PDF/A(Premium)를 활성화합니다. artisan 섹션이 있고 Chrome 브라우저 팩토리 클래스가 있으면 Chrome 렌더러 구성을 적용합니다.

has()는 컨테이너에서 하나의 문자열 식별자를 받습니다(PSR-11 §1.1.2). 전자 송장 계약은 바인딩되어 있으므로 Premium이 없어도 has()는 해당 계약에 대해 true를 반환합니다. 누락된 구체 구현은 생성 시점에만 오류를 발생시킵니다.

자동 검색 비활성화

패키지를 애플리케이션의 dont-discover 배열에 추가한 뒤 프로바이더를 수동으로 등록하세요:

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

<?php

declare(strict_types=1);

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

구성 확인 순서

각 키는 다음 순서로 확인됩니다: 환경 변수 → 게시된 config/nextpdf.php 값 → register()에서 병합된 패키지 기본값. 대부분의 키는 NEXTPDF_* 이름과 레거시 TCPDF_* 환경 이름을 모두 허용합니다. NEXTPDF_*를 사용하는 것이 좋습니다.

진단

php artisan package:discover --ansi

출력에 nextpdf/laravel이 나열된 줄이 있으면 검색 성공을 확인할 수 있습니다. 프로바이더가 지연되기 때문에 바인딩 자체는 처음 확인하기 전까지는 나타나지 않습니다. 검색 결과 줄이 올바른 성공 신호입니다.

엣지 케이스 및 주의 사항

구성 게시는 콘솔 컨텍스트에서만 등록되므로 웹 전용 요청은 이를 트리거하지 않습니다. CLI에서 vendor:publish를 실행하세요.
provides()에는 레지스트리, 팩토리, HTTP 클라이언트, 서명자, 타임스탬프, 문서 키와 함께 네 개의 전자 송장 계약 키가 포함됩니다.
새로 설치한 경우 처음으로 관련 항목을 확인하기 전까지는 비활성 상태로 보일 수 있습니다. 이는 결함이 아니라 지연 프로바이더의 설계입니다.

성능

register()는 O(1)입니다. 클로저만 사용하기 때문입니다. 글꼴 레지스트리 워밍업은 미리 로드된 글꼴에 대해 O(f)이며 워커 프로세스당 한 번 실행됩니다. 프로바이더를 지연하면 바인딩이 실제로 사용될 때까지 NextPDF 생성 비용을 프레임워크 부팅 경로에서 제외할 수 있습니다.

보안 참고 사항

지연 설계는 부팅 시 공격 표면을 좁힙니다. 잠긴 글꼴 레지스트리는 수명이 긴 워커에서 요청 간 글꼴 상태 변경을 방지합니다. 전체 위협 범위는 /integrations/laravel/security-and-operations/를 참조하세요.

적합성

주장	출처	조항	reference_id 참조 ID
연속된 확인 결과가 바인딩 전략에 따라 다를 수 있음	PSR-11 컨테이너	§1.1.2
`has()`는 하나의 문자열 식별자를 받음	PSR-11 컨테이너	§1.1.2

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

상업적 맥락

Premium 구체 구현은 동일한 지연 바인딩 키를 통해 확인됩니다. 이는 선택적인 Enterprise 기능이며, 여기에 설명된 Core 패키지는 이를 도입하기 위해 코드를 변경할 필요가 없습니다. <https://nextpdf.dev/get-license/?를 참조하세요.intent=laravel-signing>.

참고 항목

/integrations/laravel/install/ — 설치 및 게시
/integrations/laravel/overview/ — 패키지 아키텍처
/integrations/laravel/integration/ — 엔드 투 엔드 연결 방법
/integrations/laravel/configuration/ — 모든 구성 키