NextPDF Laravel 패키지 구성

한눈에 보기

config/nextpdf.php는 php artisan vendor:publish --tag=nextpdf-config로 게시됩니다. 모든 키에는 환경 변수 대체값과 하드코딩된 기본값이 있습니다. 이 페이지는 패키지의 config/nextpdf.php에 정의된 각 키를 그대로 문서화합니다.

설치

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

프로바이더는 register() 단계에서 패키지 기본값도 nextpdf 구성 키 아래에 병합합니다. 따라서 설정되지 않은 키는 게시 전에도 아래 값으로 대체됩니다.

개념 개요

대부분의 환경 변수는 NEXTPDF_* 이름이나 레거시 TCPDF_* 이름 중 하나를 사용할 수 있습니다. 레거시 접두사는 UPGRADE.md에 문서화된 전환 기간 동안 지원됩니다. 새 배포에서는 NEXTPDF_* 형식을 사용해야 합니다. 구성 파일은 다음 순서로 값을 확인합니다: 환경 변수 → 게시된 파일 값 → 패키지 기본값.

API 표면 — 구성 키

문서 레이아웃

키	환경 변수(기본)	기본값	효과
`page_format`	`NEXTPDF_PAGE_FORMAT`	`A4`	기본 페이지 형식(A4, A3, A5, Letter, Legal, Tabloid)
`orientation`	`NEXTPDF_ORIENTATION`	`P`	세로(`P`) 또는 가로(`L`)
`unit`	`NEXTPDF_UNIT`	`mm`	측정 단위(pt, mm, cm, in)
`defaults.creator`	`NEXTPDF_CREATOR`	`NextPDF`	문서 작성자 메타데이터. `PdfDocumentInterface` 바인딩에 적용됩니다
`defaults.author`	`NEXTPDF_AUTHOR`	(비어 있음)	작성자 메타데이터. 비어 있지 않은 경우에만 적용됩니다
`defaults.language`	`NEXTPDF_LANG`	`en`	문서 언어. 문서 바인딩에 적용됩니다
`defaults.margin_top` / `_right` / `_bottom` / `_left`	—	`10`	기본 여백
`defaults.font_family`	—	`dejavusans`	기본 글꼴 패밀리
`defaults.font_size`	—	`12`	기본 글꼴 크기
`defaults.trim_box`	—	`null`	포인트 단위의 TrimBox `[left, bottom, right, top]` 또는 `null`
`defaults.bleed_box`	—	`null`	포인트 단위의 BleedBox `[left, bottom, right, top]` 또는 `null`

프로바이더는 새로 확인되는 모든 문서에 defaults.creator, defaults.language, 그리고 (설정된 경우) defaults.author를 적용합니다. 값이 비어 있으면 defaults.author 적용은 건너뜁니다.

아카이브 및 색상

키	환경 변수(기본)	기본값	효과
`pdfa`	`NEXTPDF_PDFA`	`null`	PDF/A 아카이브 수준(`null`, `4`, `4e`, `4f`). null이 아닌 값은 문서 바인딩에서 PDF/A를 활성화하며, 필요한 패키지는 `nextpdf/premium`입니다
`fonts_path`	`NEXTPDF_FONTS_PATH`	`resource_path('fonts')`	추가 TrueType 글꼴 디렉터리. 글꼴 레지스트리 검색 경로를 제어합니다
`cache_path`	`NEXTPDF_CACHE_PATH`	`storage_path('framework/cache/tcpdf')`	파싱된 글꼴 및 임시 파일 캐시 디렉터리
`icc_profile.rgb`	`NEXTPDF_ICC_PROFILE_RGB`	`null`	RGB ICC 프로파일 경로. PDF/A에 필요합니다
`icc_profile.cmyk`	`NEXTPDF_ICC_PROFILE_CMYK`	`null`	인쇄 워크플로용 선택 사항인 CMYK ICC 프로파일
`font_cache_locking`	`NEXTPDF_FONT_CACHE_LOCKING`	`true`	여러 큐 워커가 동시에 쓰기 작업을 할 때 손상을 방지하도록 글꼴 캐시에 `flock`을 사용합니다

pdfa를 null이 아닌 값으로 설정하려면 Premium 티어가 필요합니다. Premium이 없으면 nextpdf/premium 없이 pdfa가 설정된 상태에서 문서 바인딩을 확인할 때 PDF/A 버전 유형에 대한 class-not-found 오류가 발생합니다. 이 페이지에서는 Premium 아카이브 동작을 설명하지 않습니다. Premium 문서를 참조하세요.

워커 메모리(장기 실행 런타임)

키	환경 변수(기본)	기본값	효과
`preload_fonts`	—	`[]`	워커 부팅 시 파싱되는 절대 글꼴 파일 경로 목록. 글꼴 레지스트리는 워밍업 후 잠깁니다
`image_cache_mb`	`NEXTPDF_IMAGE_CACHE_MB`	`50`	MB 단위의 LRU 이미지 캐시 예산. `0`은 캐싱을 비활성화합니다. 프로바이더 수준에서 상한이 적용되지 않습니다

이미지 캐시 예산에는 프로바이더가 강제 적용하는 상한이 없습니다. 이를 제한하려면 컨테이너 메모리 한도 또는 php.inimemory_limit을 적용하세요. 구성 파일은 실용적인 최대치로 256 MB를 권장합니다.

디지털 서명(Premium)

키	환경 변수(기본)	기본값	효과
`signature.enabled`	`NEXTPDF_SIGN_ENABLED`	`false`	false인 경우(또는 인증서가 비어 있는 경우), `SignerInterface`가 확인되는 값은 `null`
`signature.certificate`	`NEXTPDF_SIGN_CERT`	`null`	서명 인증서 경로
`signature.private_key`	`NEXTPDF_SIGN_KEY`	`null`	개인 키 경로
`signature.password`	`NEXTPDF_SIGN_PASSWORD`	(비어 있음)	키 암호
`signature.extra_certs`	—	`[]`	중간 CA 인증서 경로
`signature.level`	`NEXTPDF_SIGN_LEVEL`	`B-B`	서명자에게 전달되는 PAdES 기준 수준

여기서 문서화한 Core 패키지에는 서명자 구현체가 포함되어 있지 않습니다. SignerInterface 바인딩이 null로 확인되는 상태는 nextpdf/premium이 서명자를 제공할 때까지 지속됩니다. Premium에서는 level: B-B가 PAdES B-B 기준 서명을 생성합니다. 더 높은 PAdES 기준은 구성된 타임스탬프 기관과 Premium 기능에 의존합니다. 이 페이지는 해당 수준을 문서화하지 않습니다.

타임스탬프 기관

키	환경 변수(기본)	기본값	효과
`tsa.url`	`NEXTPDF_TSA_URL`	`null`	TSA 엔드포인트. 비어 있으면 `TsaClient`는 `null`로 확인됩니다
`tsa.username` / `tsa.password`	`NEXTPDF_TSA_USERNAME` / `_PASSWORD`	(비어 있음)	TSA HTTP 자격 증명
`tsa.cert` / `tsa.key`	`NEXTPDF_TSA_CERT` / `_KEY`	`null`	TSA로의 mTLS용 클라이언트 인증서 / 키
`tsa.timeout`	`NEXTPDF_TSA_TIMEOUT`	`30`	PSR-18 클라이언트의 HTTP 시간 제한(초)
`tsa.pinned_public_keys`	—	`[]`	Base64 SHA-256 SPKI 핀(RFC 7469). 비어 있으면 피닝을 비활성화합니다
`tsa.warn_on_key_rotation`	`NEXTPDF_TSA_WARN_ROTATION`	`true`	TSA가 핀으로 지정되지 않은 SPKI를 제시할 때 경고를 발생시킵니다
`tsa.allow_insecure_http`	`NEXTPDF_TSA_ALLOW_INSECURE_HTTP`	`false`	TSA로의 평문 HTTP를 허용합니다. 프로덕션에서는 false로 두세요

OCSP 응답 캐시

키	환경 변수(기본)	기본값	효과
`ocsp_cache.enabled`	`NEXTPDF_OCSP_CACHE_ENABLED`	`true`	검증 중 OCSP 응답을 캐시합니다
`ocsp_cache.ttl`	`NEXTPDF_OCSP_CACHE_TTL`	`86400`	캐시 TTL(초)
`ocsp_cache.directory`	`NEXTPDF_OCSP_CACHE_DIR`	`null`	캐시 디렉터리. `null`은 캐시를 메모리에만 유지합니다

큐

키	환경 변수(기본)	기본값	효과
`queue.connection`	`NEXTPDF_QUEUE_CONNECTION`	`null`	큐 연결. `null`은 기본 연결을 사용합니다
`queue.queue`	`NEXTPDF_QUEUE_NAME`	`pdf`	큐 이름. `GeneratePdfJob`이 여기로 푸시됩니다
`queue.timeout`	`NEXTPDF_QUEUE_TIMEOUT`	`120`	작업당 시간 제한(초)

Chrome CDP 렌더러(Artisan 확장)

키	환경 변수(기본)	기본값	효과
`artisan.chrome_binary`	`NEXTPDF_ARTISAN_CHROME_BINARY`	env 값 또는 미설정	Chrome/Chromium 바이너리 경로
`artisan.render_timeout`	`NEXTPDF_ARTISAN_RENDER_TIMEOUT`	`30`	렌더링 시간 제한(초)
`artisan.default_css`	`NEXTPDF_ARTISAN_DEFAULT_CSS`	(비어 있음)	렌더링된 HTML에 주입되는 기본 CSS
`artisan.no_sandbox`	`NEXTPDF_ARTISAN_NO_SANDBOX`	`false`	Chrome 샌드박스를 비활성화합니다
`artisan.max_html_size`	`NEXTPDF_ARTISAN_MAX_HTML_SIZE`	`5000000`	최대 HTML 입력 크기(바이트)

이 artisan 섹션은 Chrome 브라우저 팩토리 클래스가 있는 경우(nextpdf/artisan 확장)에만 문서 바인딩에 적용됩니다. 클래스가 없으면 해당 섹션은 무시됩니다.

코드 샘플 — 프로덕션

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

예외 사례 및 주의점

signature.enabled = true이지만 signature.certificate가 비어 있으면 SignerInterface는 여전히 null로 확인됩니다. 둘 다 설정해야 합니다.
tsa.url = null은 TsaClient를 null로 강제하며, 이는 다른 tsa.* 키가 채워져 있더라도 적용됩니다.
signature.level = null은 서명자에서 PAdES B-B로 대체됩니다.
image_cache_mb를 null로 설정하면(0이 아님) 50 MB 기본값으로 대체됩니다. 0은 캐싱을 명시적으로 비활성화합니다.
레거시 TCPDF_* 환경 변수는 계속 읽히지만 더 이상 사용되지 않습니다. NEXTPDF_*로 마이그레이션하세요.

성능

구성을 읽는 것은 O(1) 배열 접근입니다. preload_fonts는 워커 부팅 시 일회성 O(f) 파싱 비용으로 첫 요청 지연을 줄입니다. image_cache_mb가 클수록 프로세스 상주 메모리를 더 사용하는 대신 반복적인 이미지 디코딩을 줄입니다.

보안 참고

tsa.allow_insecure_http은 타임스탬프 신뢰를 약화시키며 프로덕션에서는 false로 유지해야 합니다. TSA URL은 신뢰할 수 있는 구성에서만 가져와야 합니다. 관리자 화면을 통해 노출되는 경우 요청 위조를 완화하기 위해 이그레스 방화벽 또는 DNS 정책을 적용하세요. 자세한 내용은 /integrations/laravel/security-and-operations/를 참조하세요.

적합성

구성 파일 형식을 규율하는 규범적 표준은 없습니다. 모든 키는 문서화된 리비전에서 패키지의 config/nextpdf.php에 대해 검증됩니다. 서명 수준 의미 체계는 Premium에서 규율하며 이 Core 페이지의 범위를 벗어납니다.

상업적 맥락

signature 및 tsa 섹션은 nextpdf/premium이 설치된 경우 Premium 서명을 제어합니다. 이는 선택적 Enterprise 기능입니다. 여기서 문서화한 Core 패키지에서는 이를 도입하기 위해 코드 변경이 필요하지 않습니다. <https://nextpdf.dev/get-license/?를 참조하세요 intent=laravel-signing>.