NextPDF Gotenberg 통합

한눈에 보기

이 페이지에서는 브리지를 애플리케이션의 다른 부분과 연결하는 방법을 다룹니다. 설치하고 연결한 뒤, 변환된 PDF를 NextPDF 후처리 파이프라인에 결합합니다. 브리지는 Office 문서를 PDF로 변환하고, 파이프라인은 이후의 모든 작업을 처리합니다. 이 페이지는 /integrations/gotenberg/boot-and-discovery/의 작업 중심 동반 문서이며, 해당 문서는 연결 방식이 왜 이런 형태인지 설명합니다.

설치

composer require nextpdf/gotenberg

이 명령은 nextpdf/core ^3.0 및 PSR HTTP 계약을 가져옵니다. PSR-18 클라이언트와 PSR-17 팩토리는 별도 패키지로 직접 설치하십시오. 브리지는 인터페이스에만 의존하므로 구체적인 라이브러리는 사용자가 선택합니다. Gotenberg 서비스를 HTTPS로 실행하는 방법을 포함한 전체 설치 과정은 /integrations/gotenberg/install/을 참조하십시오.

연결

구성 객체와 PSR 협력 객체를 사용해 브리지를 생성합니다. 응답 팩토리도 함께 주입하면 DNS 고정과 TLS 고정 전송이 활성화됩니다:

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: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

브리지는 구성된 URL에 HTTPS를 요구합니다. 어떤 요청도 보내기 전에 일반 http://를 거부합니다. Gotenberg를 TLS 종단 처리 뒤에서 실행하고, 브리지가 HTTPS 엔드포인트를 가리키도록 하십시오.

컨테이너 바인딩

호스트 컨테이너에는 세 가지를 등록하십시오. 첫 번째는 구성 소스에서 빌드한 GotenbergConfig입니다. 두 번째는 PSR-18 클라이언트와 PSR-17 팩토리입니다. 세 번째는 이 객체들로 연결한 GotenbergBridge입니다. 이 패키지는 자체 바인딩을 제공하지 않습니다. 기본 프레임워크 등록은 전용 프레임워크 통합 패키지의 역할입니다. /integrations/gotenberg/boot-and-discovery/을 참조하십시오.

구성

서비스 디스크립터와 해당 제한은 모두 GotenbergConfig의 필드입니다. 여기에는 API URL, 타임아웃, 크기 상한, 베어러 토큰, TLS 핀이 포함됩니다. 요청별 옵션인 landscape와 nativePageRanges는 이와 달리 페이로드 타입의 필드입니다. /integrations/gotenberg/configuration/에는 모든 필드의 타입, 기본값, 효과가 문서화되어 있습니다.

변환된 PDF를 NextPDF 파이프라인에 결합하기

일반적인 종단 간 흐름은 다음과 같습니다:

1. convertFile() 또는 convertString()로 Office 문서를 변환합니다.
2. 원시 PDF 바이트가 담긴 $result->pdfData를 가져와 NextPDF 문서로 로드합니다.
3. 페이지 조립, 워터마킹, PDF/A 변환, 디지털 서명과 같은 후처리를 적용합니다.

3단계는 브리지가 아니라 NextPDF의 책임입니다. nextpdf/premium 패키지는 서명, PDF/A 프로파일, 워터마킹을 제공합니다. 변환과 후처리는 별도의 단계로 유지하십시오. 그러면 각 실패를 개별적으로 진단할 수 있습니다.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

Pro 에디션의 PAdES 지원은 B-B 베이스라인 전용입니다. 이는 B-T, B-LT, B-LTA를 제공하지 않는다는 의미입니다. 이 브리지를 통해 문서를 변환하더라도 타임스탬프나 장기 검증 기능이 제공된다는 뜻은 아닙니다.

스모크 테스트

연결 후에는 통합이 정상인지 확인합니다. 실제 문서를 변환하지 않고도 확인할 수 있습니다:

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

isAvailable()는 네트워크 트래픽 없이 URL을 검증합니다. 그런 다음 <apiUrl>/health에 HEAD를 보냅니다. 그 후 정상으로 알려진 작은 문서 하나를 변환합니다. 이 단계는 <apiUrl>/forms/libreoffice/convert로 향하는 전체 멀티파트 경로를 거치고 응답 검증까지 수행합니다.

공개 API 진입점

이 통합이 사용하는 공개 표면:

• GotenbergConfig — 불변 서비스 디스크립터 및 제한; fromArray()는 구성 배열에서 이를 빌드합니다.
• GotenbergBridge::convertFile(string $path) — 디스크에 있는 파일을 변환합니다.
• GotenbergBridge::convertString(string $bytes, string $fileName) — 메모리에 담긴 바이트를 변환합니다.
• GotenbergBridge::isAvailable() — 예외를 던지지 않는 준비 상태 프로브.
• GotenbergConvertResult — pdfData, sourceFormat, isValid(), size()를 포함합니다.
• GotenbergConvertException — 변환 계층 예외 타입입니다.

전체 계약은 /integrations/gotenberg/configuration/ 및 /integrations/gotenberg/troubleshooting/에 있습니다. 여기에는 전송 선택지와 예외 카탈로그가 포함됩니다.

참고

• /integrations/gotenberg/boot-and-discovery/ — 연결 방식이 왜 이런 형태인지.
• /integrations/gotenberg/quickstart/ — 안내에 따라 진행하는 첫 변환.
• /integrations/gotenberg/production-usage/ — 시크릿, 재시도, 타임아웃, 가관측성.
• /integrations/gotenberg/install/ — 패키지 및 Gotenberg 서비스 설치.