CodeIgniter 4용 NextPDF 구성

한눈에 보기

구성은 NextPDF\CodeIgniter\Config\NextPdf에 있으며 CodeIgniter BaseConfig의 하위 클래스입니다. 값을 재정의하려면 app/Config/에서 클래스를 확장하거나 .env 키에 nextpdf. 접두사를 붙여 설정합니다. 기본값은 별도 구성 없이도 작동합니다.

개념 개요

NextPdf는 타입이 지정된 BaseConfig입니다. 이는 의도적으로 final이 아닙니다. CodeIgniter의 관례상 애플리케이션 구성은 패키지 클래스를 확장하므로, 애플리케이션이 기본값을 재정의할 수 있습니다. CodeIgniter가 구성을 생성할 때 BaseConfig는 모든 공개 속성의 환경 재정의를 해석합니다. 중첩된 배열 키도 이 해석에 포함됩니다.

기본 글꼴과 캐시 경로는 CodeIgniter의 WRITEPATH 상수를 사용합니다. 즉 WRITEPATH . 'fonts'와 WRITEPATH . 'cache/nextpdf'입니다.

구성 키

아래의 모든 키는 NextPdf의 공개 속성입니다. 기본값은 패키지 소스에서 확인된 값입니다.

페이지 및 문서 기본값

키	유형	기본값	설명
`pageFormat`	`string`	`A4`	페이지 형식.
`orientation`	`string`	`P`	`P`는 세로 방향, `L`은 가로 방향입니다.
`unit`	`string`	`mm`	측정 단위.
`defaults.creator`	`string`	`NextPDF`	PDF 작성자 메타데이터.
`defaults.author`	`string`	`''`	작성자 메타데이터. 비어 있으면 건너뜁니다.
`defaults.language`	`string`	`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`	`string`	`dejavusans`	기본 글꼴 패밀리.
`defaults.font_size`	`float`	`12.0`	기본 글꼴 크기.
`defaults.trim_box`	`list<float>\|null`	`null`	설정된 경우 사용할 트림 박스.
`defaults.bleed_box`	`list<float>\|null`	`null`	설정된 경우 사용할 블리드 박스.

이 패키지는 모든 문서에 defaults.creator와 defaults.language를 적용합니다. defaults.author는 값이 비어 있지 않을 때만 적용합니다.

경로 및 캐시

키	유형	기본값	설명
`fontsPath`	`string`	`WRITEPATH/fonts`	글꼴 파일 디렉터리.
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	캐시 디렉터리.
`preloadFonts`	`list<string>`	`[]`	부팅 시 워밍업할 절대 글꼴 경로.
`imageCacheMb`	`int`	`50`	MB 단위의 이미지 LRU 캐시 예산.
`fontCacheLocking`	`bool`	`true`	워밍업 후 글꼴 캐시를 잠급니다.

글꼴 레지스트리는 스트림 래퍼(://) 또는 null 바이트가 포함된 fontsPath를 거부합니다. 거부되면 런타임 오류가 발생합니다. 자세한 내용은 /integrations/codeigniter/security-and-operations/. 항목을 참조하세요.

아카이빙 및 색상(NextPDF Pro)

키	유형	기본값	설명
`pdfa`	`string\|null`	`null`	PDF/A 버전: `4`, `4e`, `4f`.
`iccProfile.rgb`	`string\|null`	`null`	RGB ICC 프로필 경로.
`iccProfile.cmyk`	`string\|null`	`null`	CMYK ICC 프로필 경로.

pdfa는 NextPDF Pro가 설치되어 있고 아카이빙 기능을 사용할 수 있을 때만 적용됩니다. 코어만 사용하는 경우 이 키는 무시됩니다.

디지털 서명(NextPDF Pro / Enterprise)

키	유형	기본값	설명
`signature.enabled`	`bool`	`false`	서명자 서비스를 활성화합니다.
`signature.certificate`	`string\|null`	`null`	인증서 파일 경로.
`signature.private_key`	`string\|null`	`null`	개인 키 파일 경로.
`signature.password`	`string`	`''`	개인 키 암호.
`signature.extra_certs`	`list<string>`	`[]`	추가 체인 인증서 경로.
`signature.level`	`string`	`B-B`	서명 수준 식별자.

Services::pdfSigner()는 signature.enabled가 true이고 signature.certificate가 비어 있지 않은 경우를 제외하면 null을 반환합니다. 기본 수준은 B-B입니다. NextPDF Pro는 B-B 기준 서명을 제공합니다. 장기 검증 수준은 별도의 Enterprise 기능이며, Premium 참조 문서에서 설명합니다.

PAdES B-T는 Core 엔진에서 생성됩니다. CodeIgniter 통합 자체는 B-T를 추가하지 않으며, Pro는 B-B 기준만 제공합니다. 이 문서는 Pro B-T가 출시되면 업데이트됩니다.

타임스탬프 기관(Time Stamp Authority)

키	유형	기본값	설명
`tsa.url`	`string\|null`	`null`	TSA 엔드포인트 URL.
`tsa.username`	`string`	`''`	TSA 기본 인증 사용자 이름.
`tsa.password`	`string`	`''`	TSA 기본 인증 암호.
`tsa.cert`	`string\|null`	`null`	클라이언트 인증서 경로.
`tsa.key`	`string\|null`	`null`	클라이언트 키 경로.
`tsa.timeout`	`int`	`30`	요청 시간 초과(초).
`tsa.pinned_public_keys`	`list<string>`	`[]`	고정된 TSA 공개 키.
`tsa.warn_on_key_rotation`	`bool`	`true`	TSA 키 회전 시 경고.
`tsa.allow_insecure_http`	`bool`	`false`	TSA에 대한 일반 텍스트 HTTP를 허용합니다.

Services::tsaClient()는 tsa.url이 null이거나 빈 문자열일 때 null을 반환합니다. 타임스탬프가 필요한 서명 수준이 선택되면 서명자가 TSA 클라이언트를 자동으로 연결합니다.

OCSP 캐시

키	유형	기본값	설명
`ocspCache.enabled`	`bool`	`true`	OCSP 응답 캐시를 활성화합니다.
`ocspCache.ttl`	`int`	`86400`	캐시 TTL(초).
`ocspCache.directory`	`string\|null`	`null`	캐시 디렉터리. null이면 엔진 기본값.

Chrome HTML 렌더러(NextPDF Artisan)

키	유형	기본값	설명
`artisan.chrome_binary`	`string\|null`	`null`	Chrome/Chromium 바이너리 경로.
`artisan.render_timeout`	`int`	`30`	렌더링 시간 초과(초).
`artisan.default_css`	`string`	`''`	기본 스타일시트.
`artisan.no_sandbox`	`bool`	`false`	Chrome에 `--no-sandbox`를 전달합니다.
`artisan.max_html_size`	`int`	`5000000`	최대 입력 HTML 크기(바이트).

Chrome 렌더러는 artisan.chrome_binary가 설정되어 있고 nextpdf/artisan이 설치되어 있을 때만 문서에 구성됩니다.

`.env` 파일로 재정의

BaseConfig는 속성별 환경 재정의를 해석합니다. 조회 키는 소문자 짧은 클래스 이름 nextpdf 뒤에 속성 경로가 이어지는 형태입니다. 중첩 배열 키는 점으로 지정합니다. 점 형식과 밑줄 형식이 모두 허용됩니다.

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

접두사는 소문자 짧은 클래스 이름입니다. 클래스가 NextPdf로 작성되어 있어도 접두사는 nextpdf로 유지됩니다. 정규화된 형식(NextPDF\CodeIgniter\Config\NextPdf.fontsPath)도 허용됩니다.

클래스를 확장하여 재정의

타입이 지정되고 버전 관리되는 구성을 사용하려면 app/Config/에서 패키지 클래스를 확장하세요. CodeIgniter는 패키지 기본값 대신 애플리케이션 클래스를 로드합니다. 이 파일은 클래스를 선언하며 부수 효과를 일으키지 않습니다. 이는 파일이 심볼을 선언하거나 부수 효과가 있는 로직을 실행하되, 둘을 동시에 하지는 않아야 한다는 PSR-1 기대치에 부합합니다(PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

엣지 케이스와 주의사항

단일 중첩 키를 .env로 재정의하면 해당 키만 재정의되고, 배열의 나머지는 기본값을 유지합니다.
.env 값은 문자열입니다. CodeIgniter는 true/false와 숫자 문자열을 변환합니다. 리터럴 문자열로 유지해야 하는 값은 따옴표로 묶으세요.
일부만 포함한 defaults 배열로 클래스를 확장하면 배열 전체가 대체됩니다. 위에 표시된 것처럼 모든 키를 포함하세요.

보안 참고사항

인증서와 키 경로는 소스 관리 밖에 보관하세요. .env 또는 시크릿 관리자를 통해 제공하세요. 운영 환경에서는 tsa.allow_insecure_http를 false로 유지해야 합니다. 자세한 내용은 /integrations/codeigniter/security-and-operations/. 항목을 참조하세요.

적합성

애플리케이션 구성 확장 파일은 하나의 클래스를 선언하며 부수 효과가 없습니다(PSR-1 §x1.x1.p3).

상업적 맥락

NextPDF 코어는 Apache-2.0입니다. signature.* 및 pdfa 키는 NextPDF Pro 또는 Enterprise가 설치된 경우에만 적용됩니다. CodeIgniter 패키지는 해당 서비스 메서드를 노출합니다. 이러한 메서드는 일치하는 Premium 패키지가 설치될 때까지 null을 반환합니다. </get-license/? 항목을 참조하세요.intent=codeigniter-signing>.