Gotenberg API 레퍼런스

한눈에 보기

Gotenberg 패키지는 단일 서비스 브리지인 GotenbergBridge를 제공합니다. 이 브리지는 오피스 문서(docx, xlsx, pptx, odt, ods, odp)를 외부 Gotenberg 서비스에 POST로 전송해 PDF로 변환합니다. 브리지와 함께 브리지가 읽거나 전달하는 보조 값 객체도 제공됩니다. GotenbergConfig(불변 서비스 디스크립터 및 한도), OfficeFormat(지원 형식 열거형), GotenbergConvertPayload(멀티파트 요청 본문), GotenbergConvertResult(파싱된 PDF 응답)가 여기에 해당합니다. 두 번째 계층인 GotenbergSecurityPolicy, GotenbergResponseParser, PinnedCurlTransport는 브리지가 내부적으로 구동하는 검증, 파싱, 핀 고정 전송 메커니즘입니다. 사용자 지정 전송이나 테스트 코드를 작성할 때만 사용합니다.

여기서 시작하세요: HTTPS 서비스 URL로 GotenbergConfig를 구성한 다음, PSR-18 클라이언트와 PSR-17 팩토리를 사용해 GotenbergBridge에 연결합니다. 그런 다음 convertFile() 또는 convertString()을 호출하고 반환된 GotenbergConvertResult의 pdfData를 읽습니다.

일반 작업

다음은 이 패키지에서 가장 자주 수행하는 실제 작업입니다. 각 작업에는 검증되어 실행 가능한 스니펫이 제공됩니다.

디스크의 파일을 PDF로 변환

브리지에 경로를 지정합니다. 형식은 확장자에서 감지됩니다.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

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

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

$result = $bridge->convertFile('/path/to/report.docx');

\file_put_contents('/path/to/report.pdf', $result->pdfData);

동작: URL, 경로, 크기, 파일 이름을 검증하고, 하나의 멀티파트 요청을 보낸 뒤 반환된 PDF 바이트를 디스크에 기록합니다.

메모리의 바이트를 PDF로 변환

이미 바이트를 보유하고 있다면 convertString()을 사용합니다. 형식은 파일 이름을 기준으로 감지됩니다.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

if (! $result->isValid()) {
    throw new \RuntimeException('Conversion did not return a valid PDF.');
}

동작: 파일 이름에서 xlsx를 감지하고, 바이트를 변환한 뒤 사용하기 전에 결과가 %PDF 시그니처로 시작하는지 확인합니다.

변환 전 서비스 준비 상태 확인

먼저 isAvailable()로 작업 실행 여부를 확인하세요. 이 메서드는 네트워크 트래픽 없이 URL을 검증한 다음 HEAD 요청 하나를 /health로 보냅니다.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

동작: 비어 있거나 HTTPS가 아니거나 비공개 주소인 URL과 모든 네트워크 오류에 대해 false를 반환하며(예외를 던지지 않음), 변환을 시작하기 전에 빠르게 실패할 수 있게 합니다.

브리지

이 표는 브리지의 공개 표면을 설명합니다. GotenbergBridge를 구성하거나 변환 및 준비 상태 메서드를 호출할 때 사용하세요.

심볼	매개변수	기본 동작	반환값	예외 또는 실패 조건	참고
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	구성, PSR-18 클라이언트, PSR-17 팩토리, 선택적 로거, 선택적 HTML 정책, 선택적 응답 팩토리.	정책을 제공하지 않으면 `DefaultHtmlSecurityPolicy`를 사용합니다.	`GotenbergBridge`	컨테이너 연결 오류.	핀 고정이 필요할 때 응답 팩토리가 핀 고정 cURL 전송을 활성화합니다.
`GotenbergBridge::convertFile(string $filePath)`	오피스 문서의 파일 시스템 경로.	형식 감지에 파일 확장자를 사용합니다.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError`. 지원하지 않는 형식일 때 발생합니다.	실제 경로를 확인하고 가독성, 크기, 파일 이름을 점검합니다.
`GotenbergBridge::convertString(string $content, string $fileName)`	원시 바이트와 원본 파일 이름.	형식 감지에 파일 이름 확장자를 사용합니다.	`GotenbergConvertResult`	`convertFile`과 동일합니다.	애플리케이션이 이미 파일 바이트를 보유한 경우 사용합니다.
`GotenbergBridge::isAvailable()`	없음.	구성이 유효할 때 `/health`로 HEAD 요청을 보냅니다.	`bool`	오류 시 `false`를 반환합니다.	준비 상태 신호 전용입니다.
`GotenbergBridge::getHtmlSecurityPolicy()`	없음.	구성된 파싱 계층 정책을 반환합니다.	`HtmlSecurityPolicyInterface`	예상되는 예외는 없습니다.	전송 계층 보안 정책을 보완합니다.

구성 및 페이로드

이 표는 두 변환 진입점이 제공하는 수준보다 더 세밀한 제어가 필요할 때 직접 구성하는 값 객체를 다룹니다. 여기에는 GotenbergConfig 서비스 디스크립터와 GotenbergConvertPayload/GotenbergConvertResult 요청 및 응답 캐리어가 포함됩니다.

심볼	매개변수	기본 동작	반환값	예외 또는 실패 조건	참고
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	API URL, 타임아웃, 최대 파일 크기, 베어러 토큰, 핀 세트.	빈 URL은 유효하지 않으며, 기본 최대 크기는 50 MiB입니다.	`GotenbergConfig`	예상되는 예외는 없습니다.	API 키는 비밀로 유지하세요.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, 핀 배열.	누락된 선택 값에는 생성자 기본값을 사용합니다.	`GotenbergConfig`	예상되는 예외는 없습니다.	문자열 목록에서는 문자열이 아닌 값을 무시합니다.
`GotenbergConfig::isValid()`	없음.	API URL이 비어 있지 않으면 유효합니다.	`bool`	예상되는 예외는 없습니다.	URL 안전성은 네트워크 I/O 이전에 검증됩니다.
`GotenbergConfig::allPublicKeyPins()`	없음.	기본 핀과 백업 핀을 결합합니다.	`list<string>`	예상되는 예외는 없습니다.	빈 목록은 핀 고정을 비활성화합니다.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	파일 이름, 바이트, 형식, 방향 플래그, 페이지 범위.	세로 방향, 모든 페이지가 기본값입니다.	`GotenbergConvertPayload`	예상되는 예외는 없습니다.	페이로드는 멀티파트 폼 데이터로 변환됩니다.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	멀티파트 경계.	비어 있지 않을 때만 페이지 범위 필드를 포함합니다.	`string`	예상되는 예외는 없습니다.	경계는 브리지가 생성합니다.
`GotenbergConvertPayload::contentType(string $boundary)`	멀티파트 경계.	`multipart/form-data`를 사용합니다.	`string`	예상되는 예외는 없습니다.	요청의 `Content-Type`로 첨부합니다.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	변환된 PDF 바이트, 소스 형식, 선택적 렌더링 소요 시간.	측정하지 않으면 렌더링 소요 시간은 `0.0`입니다.	`GotenbergConvertResult`	예상되는 예외는 없습니다.	`GotenbergResponseParser::parse()`에서 반환됩니다.
`GotenbergConvertResult::isValid()`	없음.	변환된 PDF 바이트가 비어 있지 않고 PDF 데이터처럼 보이면 유효합니다.	`bool`	예상되는 예외는 없습니다.	결과를 영속화하거나 스트리밍하기 전에 확인하세요.
`GotenbergConvertResult::size()`	없음.	변환된 PDF 바이트 수를 셉니다.	`int`	예상되는 예외는 없습니다.	할당량, 텔레메트리, 응답 한도에 사용합니다.

오피스 형식

이 표는 OfficeFormat 열거형을 설명합니다. 확장자를 형식에 매핑하거나, 업로드 MIME 유형을 읽거나, 지원되는 여섯 가지 형식을 확인해야 할 때 사용하세요.

심볼	매개변수	기본 동작	반환값	예외 또는 실패 조건	참고
`OfficeFormat::fromExtension(string $ext)`	선행 점이 있거나 없는 파일 확장자.	대소문자를 구분하지 않고 일치시킵니다.	`OfficeFormat`	`ValueError`. 지원하지 않는 확장자일 때 발생합니다.	지원되는 값: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	없음.	열거형 케이스를 업로드 MIME 유형에 매핑합니다.	`string`	예상되는 예외는 없습니다.	멀티파트 파일 파트에 사용됩니다.
`OfficeFormat::extension()`	없음.	백킹 값을 반환합니다.	`string`	예상되는 예외는 없습니다.	진단 및 파일 이름에 유용합니다.

보안, 파싱 및 전송

이 표는 브리지가 사용자를 대신해 구동하는 내부 메커니즘을 설명합니다. 사용자 지정 전송, 패키지 파싱이 여전히 필요한 맞춤형 HTTP 호출, 또는 저수준 보안 및 핀 고정 진단을 작성할 때만 사용하세요.

심볼	매개변수	기본 동작	반환값	예외 또는 실패 조건	참고
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	API 기본 URL.	네트워크 I/O 이전에 대상을 파싱하고 검증합니다.	`array`	`RuntimeException`. 안전하지 않거나 유효하지 않은 URL일 때 발생합니다.	SSRF 방식의 엔드포인트 실수를 변환 코드에서 배제합니다.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	호스트와 핀 고정 IP 목록.	DNS 핀 기대치를 검증합니다.	`void`	`RuntimeException`. 핀이 오래되었거나 유효하지 않을 때 발생합니다.	핀 고정 배포 및 운영 진단에 사용합니다.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	실제 크기와 구성된 최대값.	구성된 한도 이하의 파일만 허용합니다.	`void`	`RuntimeException`. 파일이 너무 클 때 발생합니다.	요청 구성 이전에 적용하세요.
`GotenbergSecurityPolicy::validateFileName(string $name)`	원본 파일 이름.	안전하지 않거나 지원되지 않는 파일 이름 형식을 거부합니다.	`void`	`RuntimeException`. 유효하지 않은 이름일 때 발생합니다.	잘못된 형식의 멀티파트 파일 이름을 방지합니다.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	PSR-7 응답과 예상 오피스 형식.	성공 응답에서 변환된 PDF 바이트를 추출합니다.	`GotenbergConvertResult`	`GotenbergConvertException`. 실패 응답 또는 유효하지 않은 PDF 출력일 때 발생합니다.	파일 변환과 문자열 변환 모두를 위한 중앙 파서입니다.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	PSR-17 팩토리, 핀 고정 IP, 핀 고정 공개 키, 타임아웃.	핀 없음과 30 초 타임아웃이 기본값입니다.	`PinnedCurlTransport`	예상되는 예외는 없습니다.	cURL 수준 핀 고정이 필요할 때만 사용합니다.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	PSR-7 요청.	구성된 타임아웃 및 핀 고정 제어와 함께 cURL을 통해 전송합니다.	`ResponseInterface`	`GotenbergConvertException`. cURL/전송 실패 시 발생합니다.	핀 고정을 다른 HTTP 클라이언트에 위임할 수 없을 때 사용합니다.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	요청, 호스트, 포트.	`sendRequest()`에서 사용하는 cURL 옵션 배열을 빌드합니다.	`array`	유효하지 않은 요청 또는 핀 구성 오류.	저수준 진단 및 테스트 훅입니다.

개발 참고 사항

Gotenberg를 외부 서비스 경계로 취급하세요. 타임아웃, 크기, URL, 핀 정책을 신중하게 구성하세요.
convertFile()은 요청 구성 이전에 파일 전체를 메모리로 읽어 들입니다.
파일 내용이 아니라 파일 이름과 콘텐츠 길이 같은 메타데이터를 로깅하세요.