NextPDF Symfony 번들 구성

한눈에 보기

번들의 모든 동작은 nextpdf 루트 키 아래의 config/packages/nextpdf.yaml 파일에서 설정합니다. 모든 키에는 기본값이 있으므로 별도 구성은 선택 사항입니다. 이 페이지는 Configuration.php 파일의 내용을 그대로 반영합니다.

구성 트리

스키마는 NextPDF\Symfony\DependencyInjection\Configuration에서 정의합니다. 잘못된 값이 있으면 컨테이너 빌드 시점에 Symfony InvalidConfigurationException 예외가 발생하며 실패합니다.

최상위 키

키	유형	기본값	유효성 검사
`page_format`	enum	`A4`	다음 중 하나: `A4`, `A3`, `A5`, `Letter`, `Legal`, `Tabloid`
`orientation`	enum	`P`	다음 중 하나: `P`, `L`
`unit`	enum	`mm`	다음 중 하나: `pt`, `mm`, `cm`, `in`
`pdfa`	scalar	`null`	다음 중 하나: `null`, `4`, `4e`, `4f`
`fonts_path`	scalar	`%kernel.project_dir%/resources/fonts`	—
`cache_path`	scalar	`%kernel.cache_dir%/nextpdf`	—
`image_cache_mb`	integer	`50`	최소 `0`
`font_cache_locking`	boolean	`true`	—
`preload_fonts`	문자열 목록	`[]`	—

`icc_profile`

키	유형	기본값
`icc_profile.rgb`	scalar	`null`
`icc_profile.cmyk`	scalar	`null`

`defaults`

이 설정은 PdfFactory가 생성하는 모든 문서에 적용됩니다.

키	유형	기본값
`defaults.creator`	scalar	`NextPDF`
`defaults.author`	scalar	(비어 있음)
`defaults.language`	scalar	`en`
`defaults.margin_top`	float	`10.0`
`defaults.margin_right`	float	`10.0`
`defaults.margin_bottom`	float	`10.0`
`defaults.margin_left`	float	`10.0`
`defaults.font_family`	scalar	`dejavusans`
`defaults.font_size`	float	`12.0`
`defaults.trim_box`	variable	`null`
`defaults.bleed_box`	variable	`null`

PdfFactory는 이 섹션에서 creator, author, language를 읽어 새 문서마다 적용합니다. 나머지 키는 엔진에서 사용할 수 있도록 컨테이너 매개변수로 저장됩니다.

`artisan`

이 설정은 nextpdf/artisan이 설치되어 감지된 경우에만 적용됩니다.

키	유형	기본값
`artisan.chrome_binary`	scalar	`null`
`artisan.render_timeout`	integer	`30`
`artisan.default_css`	scalar	(비어 있음)
`artisan.no_sandbox`	boolean	`false`
`artisan.max_html_size`	integer	`5000000`

`signature`

이 설정은 nextpdf/premium이 설치된 경우에만 적용됩니다. 번들과 Pro 등급이 함께 설치되어 있으면 지원되는 서명 구성은 베이스라인 B-B 프로필입니다. level 노드는 더 넓은 NextPDF 구성 제품군과 스키마 호환성을 유지하기 위해 아래에 나열된 문자열 값을 허용합니다. 이 번들이 제공하는 서명 기능은 B-B입니다. B-B를 넘어서는 프로필은 NextPDF Premium 문서에서 별도로 다루며, 여기에서는 이를 주장하지 않습니다.

키	유형	기본값	유효성 검사
`signature.enabled`	boolean	`false`	—
`signature.certificate`	scalar	`null`	—
`signature.private_key`	scalar	`null`	—
`signature.password`	scalar	(비어 있음)	—
`signature.extra_certs`	문자열 목록	`[]`	—
`signature.level`	enum	`B-B`	허용 집합: `B-B`, `B-T`, `B-LT`, `B-LTA` (B-B 제공; `B-T`/`B-LT`/`B-LTA`는 스키마 호환성 값이며 제공되는 Pro 기능이 아님)

컴파일러 패스는 signature.enabled가 true이고 또한 signature.certificate가 설정된 경우에만 서명자 서비스를 등록합니다. 그렇지 않으면 이 섹션은 비활성 상태로 유지됩니다.

`tsa`

타임스탬프 기관(TSA) 클라이언트 구성입니다. 설정된 경우 Pro 서명에 사용됩니다.

키	유형	기본값
`tsa.url`	scalar	`null`
`tsa.username`	scalar	(비어 있음)
`tsa.password`	scalar	(비어 있음)
`tsa.cert`	scalar	`null`
`tsa.key`	scalar	`null`
`tsa.timeout`	integer	`30`
`tsa.allow_insecure_http`	boolean	`false`
`tsa.pinned_public_keys`	문자열 목록	`[]`
`tsa.warn_on_key_rotation`	boolean	`true`

TSA 클라이언트 서비스는 tsa.url이 설정된 경우에만 등록됩니다.

`ocsp_cache`

키	유형	기본값
`ocsp_cache.enabled`	boolean	`true`
`ocsp_cache.ttl`	integer	`86400`
`ocsp_cache.directory`	scalar	`null`

`messenger`

이 설정은 symfony/messenger가 설치된 경우에 사용되는 비동기 생성 옵션입니다.

키	유형	기본값
`messenger.transport`	scalar	`async`
`messenger.timeout`	integer	`120`
`messenger.retries`	integer	`3`

참조 구성

모든 섹션과 그 기본값을 보여 주는 구성 파일입니다:

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

컨테이너 서비스 및 별칭

번들은 config/services.php에서 서비스 정의를 로드합니다. 아래 표는 해당 파일의 내용을 그대로 반영합니다.

서비스 ID	공유	공개	비고
`NextPDF\Typography\FontRegistry`	예	—	다음에서 생성됨: `nextpdf.fonts_path`; 선택적 PSR-3 로거
`NextPDF\Contracts\FontRegistryInterface`	(별칭)	예	다음의 별칭: `FontRegistry`
`NextPDF\Graphics\ImageRegistry`	예	—	제한된 LRU; `kernel.reset` 태그 지정됨 (`reset`)
`NextPDF\Core\DocumentFactory`	예	—	두 레지스트리를 공유함
`NextPDF\Contracts\DocumentFactoryInterface`	(별칭)	예	다음의 별칭: `DocumentFactory`
`NextPDF\Symfony\Service\PdfFactory`	예	예	`defaults`, `pdfa`, `artisan` 매개변수를 읽음
`NextPDF\Contracts\PdfDocumentInterface`	아니요	예	팩토리 `[PdfFactory, create]`
`NextPDF\Core\Document`	(별칭)	—	다음의 별칭: `PdfDocumentInterface`
`nextpdf.document`	(별칭)	예	다음의 별칭: `PdfDocumentInterface`
`NextPDF\Symfony\Http\PdfResponse`	—	예	상태를 갖지 않는 헬퍼

번들은 해당 Premium 구현 클래스가 존재하는 경우에 한해서만 EInvoice 계약 바인딩(EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface)을 추가로 등록합니다. 각 바인딩은 비공유로 등록되므로 호출자는 매번 새 인스턴스를 받습니다. 호출별 파서 상태는 요청 간에 절대 누출되지 않습니다.

공유 대 비공유

nextpdf.document(및 그 별칭)은 비공유입니다. 컨테이너가 해결할 때마다 별개의 문서를 반환합니다. PSR-11에서는 컨테이너가 동일한 식별자로 연속된 get() 호출을 처리할 때 서로 다른 값을 반환할 수 있습니다(PSR-11 §1.1.2). 글꼴 레지스트리는 공유되며 워밍업 후에는 잠깁니다. 따라서 구조적 글꼴 데이터는 프로세스당 한 번만 파싱되며 요청 도중에 변경될 수 없습니다.

위의 FontRegistry 및 ImageRegistry 서비스는 선택적 Psr\Log\LoggerInterface를 받아들이며, nullOnInvalid()로 바인딩됩니다. 로거는 교체 가능한 선택적 협력자이며 PSR-3 로거 계약(PSR-3)과 일관됩니다.

자동 와이어링

PdfFactory, PdfResponse, 문서 팩토리 인터페이스, 글꼴 레지스트리 인터페이스는 공개 서비스입니다. 이들은 컨테이너에서 가져오거나, 자동 와이어링된 컨트롤러 및 서비스에서 타입 힌트로 지정할 수 있습니다. NextPDF\Symfony\Service\PdfFactory의 생성자 주입이 권장되는 진입점입니다.

엣지 케이스 및 주의 사항

Pro 없이 pdfa를 설정하는 경우 — 값은 저장되지만 무시됩니다. PdfFactory는 컴파일 시점에 Pro 확장이 감지된 경우에만 PDF/A를 적용합니다.
image_cache_mb: 0 — 유효하며 이미지 LRU 캐시를 비활성화합니다. 음수 값은 빌드 시점에 거부됩니다.
signature.certificate 없이 signature.enabled: true를 설정한 경우 — 서명자 서비스가 등록되지 않습니다. 구성은 설계상 조용히 비활성 상태가 됩니다.
%kernel.*% 자리표시자 — fonts_path 및 cache_path 기본값은 Symfony 컨테이너 매개변수를 사용합니다. 리터럴 경로가 필요한 경우에만 절대 경로로 재정의하십시오.

적합성

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

사양	조항	reference_id	주장
PSR-11	`psr_11_container#1.1.2.p3.b`		get()은 해결할 때마다 서로 다른 값을 반환할 수 있음
PSR-3	`psr_3_logger#x3.p17`		선택적 LoggerInterface 협력자

상업적 맥락

signature 및 tsa 섹션은 nextpdf/premium(Pro)이 설치된 경우에만 적용됩니다. 이는 선택적 Pro 기능입니다. 여기에서 다루는 Core 번들은 이를 채택하는 데 코드 변경이 필요하지 않습니다. </get-license/?를 참조하십시오.intent=symfony-pro>.

참고 항목

/integrations/symfony/install/ — 번들 설치 및 등록.
/integrations/symfony/overview/ — 기능 요약.
/integrations/symfony/production-usage/ — 워커 안전성 및 비동기 패턴.
/integrations/symfony/boot-and-discovery/ — 부팅 중 구성이 해석되는 방식.