NextPDF Symfony 통합 개요

한눈에 보기

nextpdf/symfony는 NextPDF 엔진을 위한 공식 Symfony 7 번들입니다. 이 번들은 엔진을 Symfony 컨테이너에 연결하고, 사용자가 작성한 서비스에 주입할 수 있는 문서 팩토리를 제공합니다. 또한 HTTP 응답 헬퍼와 PDF를 비동기적으로 생성하는 경로도 제공하므로, 해당 작업을 백그라운드에서 실행할 수 있습니다.

번들이 제공하는 기능

NextPDF Symfony는 nextpdf/core 엔진을 표준 번들로 Symfony 애플리케이션에 바인딩합니다. 다음 구성 요소를 추가하며, 각 요소는 src/Symfony/의 번들 소스를 기준으로 검증되었습니다.

번들 진입점 — NextPDF\Symfony\NextPdfBundle은 Symfony Bundle 기본 클래스를 확장하며 컴파일러 패스 하나를 등록합니다.
의존성 주입 확장 — NextPDF\Symfony\DependencyInjection\NextPdfExtension은 서비스 정의를 로드하고, 구성 트리를 컨테이너 매개변수로 변환하며, 구성 별칭 nextpdf를 노출합니다.
타입이 지정된 구성 트리 — NextPDF\Symfony\DependencyInjection\Configuration은 nextpdf 구성 스키마를 정의합니다. 이 스키마는 열거형 값을 검증하고 기본값을 설정하며, %kernel.*% 매개변수 자리 표시자를 사용합니다.
주입 가능한 문서 팩토리 — NextPDF\Symfony\Service\PdfFactory는 미리 구성된 새 NextPDF\Core\Document 인스턴스를 생성합니다. Symfony 방식으로 제공되는 정적 파사드에 해당합니다.
HTTP 응답 헬퍼 — NextPDF\Symfony\Http\PdfResponse는 OWASP에 맞춘 고정된 보안 헤더 집합을 사용하여 인라인, 다운로드, 스트리밍 응답을 생성합니다.
비동기 생성 경로 — NextPDF\Symfony\Message\GeneratePdfMessage, NextPDF\Symfony\Message\GeneratePdfHandler, 그리고 NextPDF\Symfony\Message\PdfBuilderInterface는 Symfony Messenger와 통합되어 PDF 렌더링을 워커에서 실행할 수 있게 합니다.
컴파일 타임 확장 감지기 — NextPDF\Symfony\DependencyInjection\Compiler\OptionalExtensionPass는 선택적 NextPDF 확장을 감지하고, 해당 확장이 있을 때만 그 서비스를 등록합니다.

컨테이너 계약

이 번들은 작고 안정적인 공개 컨테이너 서비스 집합을 등록합니다. 문서 서비스 nextpdf.document(NextPDF\Contracts\PdfDocumentInterface 및 NextPDF\Core\Document의 별칭)는 공유되지 않습니다. 즉, 각 해결(resolution)마다 서로 다른 일회용 문서를 반환합니다. 이는 PSR-11 컨테이너 계약과 일치하며, 이 계약에 따르면 동일한 식별자에 대해 get()을 연속으로 두 번 호출해도 컨테이너 구성에 따라 서로 다른 값을 반환할 수 있습니다. PSR-11 §1.1.2를 참조하세요. 비공유 바인딩은 의도된 동작입니다. 문서는 렌더링별 상태를 누적하므로, 요청마다 새 인스턴스를 사용하면 장기 실행 워커에서 요청 간에 상태가 누출되는 것을 방지합니다.

글꼴 레지스트리(NextPDF\Contracts\FontRegistryInterface)는 반대로 동작합니다. 즉, 공유 싱글턴입니다. 이미지 레지스트리는 kernel.reset 태그를 가지므로, FrankenPHP 및 Messenger 워커 환경에서 제한된 캐시가 요청 간에 비워집니다. 전체 서비스 및 별칭 표는 구성 페이지에 문서화되어 있습니다.

선택적 로깅

글꼴 및 이미지 레지스트리는 선택적 PSR-3 로거를 받을 수 있습니다. 이 번들은 애플리케이션이 로거를 제공할 때만 Psr\Log\LoggerInterface를 바인딩합니다(nullOnInvalid()). 따라서 로깅은 필수 의존성이 아니라 선택적 협력 객체입니다. 이는 PSR-3 로거 계약과 일치하며, 이 계약에서 로거는 주입 및 교체가 가능한 협력 객체로 취급됩니다(PSR-3).

코어 기능과 선택 기능 비교

번들 자체는 Apache-2.0 코어 소프트웨어입니다. 일부 기능은 선택적 패키지를 함께 설치한 경우에만 제공됩니다.

기능	필요 항목	감지 방식
PDF 생성, `PdfFactory`, `PdfResponse`	코어만	항상 사용 가능
비동기 생성	`symfony/messenger`	Messenger가 설치되면 핸들러가 활성화됨
Chrome CDP HTML 렌더링	`nextpdf/artisan`	컴파일 타임 `class_exists` 검사
PDF/A 보존, 디지털 서명	`nextpdf/premium`(Pro 설치)	컴파일 타임 `class_exists` 검사

nextpdf/premium이 설치되면, 번들은 기본 PAdES B-B 서명 구성을 적용할 수 있습니다. 더 높은 서명 프로파일은 이 번들 문서의 범위를 벗어납니다. 에디션 매트릭스는 NextPDF Premium 문서를 참조하세요.

이 번들을 사용해야 하는 경우

Symfony 7 HTTP 애플리케이션 또는 워커 안에서 PDF를 생성할 때는 nextpdf/symfony를 사용하세요. 이 번들은 컨테이너가 관리하는 서비스, 워커에 안전한 레지스트리, 보안 다운로드 응답을 제공하므로, 엔진을 직접 연결할 필요가 없습니다. 스크립트에서 일회성 생성만 필요하다면, 코어 nextpdf/core 패키지만으로도 충분합니다.

적합성

각 행은 이 페이지에서 제시하는 규범적 주장이며, 게이트된 SDO 코퍼스의 전체 64자리 16진수 reference_id에 고정되어 있습니다. 출처 정보(코퍼스 매니페스트, 검색 전송)는 _sidecars/rag-citations.yaml에 있습니다.

사양	절	reference_id 참조 ID	주장
PSR-11	`psr_11_container#1.1.2.p3.b`		컨테이너 get() 반환 값 계약
PSR-3	`psr_3_logger#x3.p17`		LoggerInterface 선택적 의존성

상업적 맥락

디지털 서명과 PDF/A 보존은 nextpdf/premium(Pro)을 번들과 함께 설치할 때 사용할 수 있게 됩니다. 이는 선택적인 Pro 기능입니다. 여기에서 문서화한 Core 번들은 이 기능을 도입하기 위한 코드 변경이 필요하지 않습니다. </get-license/?를 참조하세요.intent=symfony-pro>.

함께 보기

/integrations/symfony/install/ — 번들을 설치하고 등록합니다.
/integrations/symfony/configuration/ — 전체 nextpdf 구성 트리와 서비스 표를 설명합니다.
/integrations/symfony/quickstart/ — 실행 가능한 컨트롤러와 비동기 예제를 제공합니다.
/integrations/symfony/boot-and-discovery/ — Symfony가 번들을 검색하고 부팅하는 방식입니다.
/integrations/symfony/production-usage/ — 워커 안전성, 스트리밍, 비동기 패턴을 설명합니다.