NextPDF Gotenberg 설정

한눈에 보기

구성은 두 위치에서 정의됩니다. 첫 번째는 서비스와 그 제한을 설명하는 불변 GotenbergConfig 값 객체입니다. 두 번째는 PSR HTTP 협력 객체를 연결하는 GotenbergBridge 생성자입니다. 둘 모두 명시적 생성자 주입을 사용합니다. 전역 상태가 없고, 패키지 내부에서 환경 변수를 읽지도 않으며, 숨겨진 기본 엔드포인트도 없습니다.

구성 객체

GotenbergConfig는 final readonly 값 객체입니다. 명명된 인자로 직접 생성할 수 있고, GotenbergConfig::fromArray()를 사용해 연관 배열에서 빌드할 수도 있습니다.

필드

필드	타입	기본값	효과
apiUrl	string	''	Gotenberg 서비스의 기본 URL입니다. 필수입니다. 값이 비어 있으면 구성이 유효하지 않으며 모든 변환이 즉시 실패합니다. HTTPS여야 합니다.
timeout	int	30	초 단위의 하드 전송 타임아웃입니다. cURL 고정 트랜스포트가 선택되면 해당 트랜스포트에서 적용됩니다.
maxFileSize	int	52_428_800	바이트 단위의 최대 입력 크기(50 MiB)입니다. 이보다 큰 입력은 어떤 요청도 보내기 전에 거부됩니다.
apiKey	string	''	베어러 토큰입니다. 비어 있지 않으면 Authorization: Bearer <token> 헤더로 전송됩니다. #[\SensitiveParameter]로 표시되어 스택 트레이스에서 가려집니다.
pinnedPublicKeys	list<string>	[]	sha256/<base64> 형식의 기본 TLS SPKI 핀입니다. 비어 있으면 고정이 비활성화됩니다.
backupPublicKeys	list<string>	[]	백업 TLS SPKI 핀이며, 회전을 독립적으로 검증할 수 있도록 별도로 유지됩니다.

직접 생성하기

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    maxFileSize: 20 * 1024 * 1024,
    apiKey: $secretFromYourSecretStore,
);

배열로부터 생성하기

fromArray()는 snake_case 키를 받아들이며, 잘못된 형식의 값은 예외를 던지지 않고 무시합니다. 문자열이 아닌 api_url은 ''이 됩니다. 정수가 아닌 timeout은 30으로 되돌아갑니다. 정수가 아닌 max_file_size는 50 MiB 기본값으로 되돌아갑니다. 배열이 아닌 핀 목록은 []이 됩니다. 핀 배열의 문자열이 아닌 항목은 버려집니다.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

이처럼 관대한 파싱은 의도적입니다. 따라서 별도의 사전 검증 계층 없이도 프레임워크 구성 배열을 그대로 전달해 잘 타입화된 객체를 생성할 수 있습니다. URL이 도달 가능한지 또는 핀이 올바른지는 검증하지 않습니다. 이 검사는 변환 시점에 이루어집니다.

유효성

isValid()는 apiUrl이 비어 있지 않은 문자열일 때만 true를 반환합니다. 네트워크 검사나 스킴 검사는 수행하지 않습니다. HTTPS 및 사설 주소 선별은 변환 시점에 보안 정책 내부에서 이루어집니다. 유효하지 않은 구성에서는 convertFile()와 convertString()이 Invalid Gotenberg configuration: apiUrl is empty 메시지와 함께 GotenbergConvertException을 던집니다. 유효하지 않은 구성에서는 또한 isAvailable()이 네트워크 호출 없이 false를 반환합니다.

브리지 생성자

GotenbergBridge는 구성과 PSR 협력 객체를 함께 받습니다:

인자	타입	필수	효과
config	GotenbergConfig	예	위에서 설명한 서비스 디스크립터와 제한입니다.
httpClient	Psr\Http\Client\ClientInterface	예	헬스 프로브에 사용되며 폴백 트랜스포트 역할을 하는 PSR-18 클라이언트입니다.
requestFactory	Psr\Http\Message\RequestFactoryInterface	예	PSR-7 요청을 빌드합니다.
streamFactory	Psr\Http\Message\StreamFactoryInterface	예	요청 본문 스트림을 빌드합니다.
logger	Psr\Log\LoggerInterface|null	아니요(기본값 null)	제공되면 변환 요청마다 debug 수준 항목이 로깅됩니다.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	아니요	제공하지 않으면 코어 기본 HTML 보안 정책이 사용됩니다. 파싱 계층 정책으로, 트랜스포트 계층 정책을 보완합니다.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	아니요(기본값 null)	cURL 고정 트랜스포트를 활성화하는 데 필요합니다. 이것이 없으면 브리지는 항상 주입된 PSR-18 클라이언트를 사용합니다.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    logger: $psrLogger,
    responseFactory: $psrResponseFactory,
);

트랜스포트 선택

브리지는 두 가지 트랜스포트 중 하나를 변환 요청마다 선택합니다:

• cURL 고정 트랜스포트 — responseFactory가 주입되었고 또한 고정할 대상이 있을 때(URL이 하나 이상의 IP로 해석되었거나 SPKI 핀이 구성된 경우) 사용됩니다. 이 트랜스포트는 해석된 주소 집합을 CURLOPT_RESOLVE로 바인딩합니다. 핀이 있으면 CURLOPT_PINNEDPUBLICKEY로 SPKI 고정을 강제합니다. 피어와 호스트를 검증합니다(CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). 구성된 타임아웃을 적용하고, 리디렉션 추적을 비활성화합니다(CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• 주입된 PSR-18 클라이언트 — 그 외 모든 경우에 사용되며, 여기에는 API URL이 단순한 공인 IP 리터럴(고정할 DNS가 없음)이고 SPKI 핀이 구성되지 않은 경우, 또는 responseFactory가 제공되지 않은 경우가 포함됩니다.

따라서 DNS 리바인딩에 강한 연결과 TLS 고정을 얻으려면 responseFactory를 주입하고 핀을 구성하십시오. 헬스 프로브는 트랜스포트 선택과 무관하게 항상 주입된 PSR-18 클라이언트를 사용합니다.

TLS 공개 키 고정

고정은 SHA-256 SPKI 지문 모델을 따릅니다. 각 핀은 sha256/<base64-encoded-spki-hash> 형식의 문자열입니다. 트랜스포트는 cURL 네이티브 sha256//<base64> 형식도 받아들이며, 단일 슬래시 형식을 해당 형식으로 변환합니다. 다른 접두사는 InvalidSpkiPinException을 일으킵니다.

allPublicKeyPins()는 pinnedPublicKeys와 backupPublicKeys의 중복을 제거한 합집합을 반환합니다. TLS 계층은 SPKI 해시가 결합된 집합의 구성원 중 어느 하나와 일치하는 인증서를 받아들입니다. 운영상으로는 백업 핀을 최소 하나 구성하여, 계획된 인증서 또는 키 회전 시 새 키가 전파되는 동안 브리지가 서비스 접근 불능 상태로 잠기지 않도록 해야 합니다. 백업 목록을 기본 목록과 분리해 두면 활성 핀과 독립적으로 백업 핀을 검증하고 교체할 수 있습니다. 회전 절차는 /integrations/gotenberg/security-and-operations/를 참조하십시오.

요청별 변환 옵션

멀티파트 페이로드 타입(GotenbergConvertPayload)은 파일 외에 선택적 Gotenberg 변환 옵션 두 개를 담습니다:

• landscape(bool, 기본값 false) — landscape 폼 필드에 "true" 또는 "false"로 전송됩니다.
• nativePageRanges(string, 기본값 '') — 비어 있지 않을 때만 nativePageRanges 폼 필드로 전송되며, 1-3 또는 1,3,5-9 같은 Gotenberg의 범위 구문을 받아들입니다.

공개 convertFile()와 convertString() 진입점은 이 두 필드의 기본값으로 페이로드를 빌드합니다. 두 필드는 페이로드 계약의 일부이며 테스트 스위트에서 검증됩니다. 가로 방향 출력이나 페이지 선택이 필요하면 자체 통합 계층에서 이들을 노출하십시오.

함께 보기

• /integrations/gotenberg/install/ — 설치 및 Gotenberg 기준 환경.
• /integrations/gotenberg/quickstart/ — 실행 가능한 엔드 투 엔드 예제.
• /integrations/gotenberg/production-usage/ — 구성 소싱, 비밀, 타임아웃, 재시도.
• /integrations/gotenberg/security-and-operations/ — 전체 보안 모델 및 핀 회전.
• /integrations/gotenberg/troubleshooting/ — 각 구성 관련 예외의 의미.