Gotenberg 개발자 가이드

한눈에 보기

Gotenberg 패키지는 변환 작업을 외부 서비스에 위임합니다. 애플리케이션 코드는 서비스 경계를 명확히 드러내야 합니다. 즉, 입력을 검증하고, 페이로드를 구성하고, 요청을 전송하고, 결과를 구문 분석하며, 서비스 실패를 처리해야 합니다.

이 가이드는 nextpdf/gotenberg를 중심으로 office-to-PDF 변환 워크플로, 업로드 엔드포인트, 서비스 상태 점검, 전송 정책을 구축할 때 참고하십시오.

아키텍처 경계

계층	담당 주체	책임	여기에 두지 말 것
업로드 또는 문서 소스	애플리케이션	호출자를 인가하고, 소스를 검증하며, 변환 정책을 선택합니다.	서비스 URL 또는 전송 고정 관련 결정.
형식 감지	`nextpdf/gotenberg`	안전한 확장자를 `OfficeFormat`에 매핑합니다.	애플리케이션 검증 없이 MIME을 신뢰하는 것.
브리지	`nextpdf/gotenberg`	멀티파트 요청을 구성하고, Gotenberg를 호출하며, PDF 응답을 구문 분석합니다.	도메인 쿼리 또는 스토리지 정책.
Gotenberg 서비스	배포	오피스 문서를 PDF로 변환합니다.	PHP 애플리케이션 인가.
코어 엔진	`nextpdf/nextpdf`	선택적으로 변환된 PDF 데이터를 가져오거나 결합합니다.	오피스 변환.

런타임 수명 주기

단계	동작	개발자 조치
구성 생성	API URL, 타임아웃, 최대 크기, API 키, 핀이 로드됩니다.	서비스 URL과 토큰을 소스 코드 밖에 두십시오.
입력 검증	파일 경로, 파일 크기, 파일 이름, 확장자, URL 안전성이 점검됩니다.	지원되지 않는 입력은 디스패치 전에 거부하십시오.
페이로드 구성	`GotenbergConvertPayload`는 멀티파트 폼 데이터를 구성합니다.	안전한 경우에만 원본 파일 이름을 유지하십시오.
서비스 요청	브리지는 요청을 `/forms/libreoffice/convert`로 전송합니다.	타임아웃과 전송 정책을 구성하십시오.
결과 구문 분석	`GotenbergResponseParser::parse()`는 PDF 바이트와 메타데이터를 반환합니다.	PDF가 아닌 응답이나 오류 응답은 변환 실패로 처리하십시오.

권장 애플리케이션 구조

경로	용도
`app/Pdf/Conversion/*`	애플리케이션이 `GotenbergBridge`를 감싸는 래퍼.
`app/Pdf/Uploads/*`	업로드 검증, 스토리지, 파일 이름 정책.
`app/Pdf/ConversionPolicy/*`	크기, 형식, 서비스 선택 정책.
`tests/Pdf/Conversion/*`	형식, 파일, 서비스, 전송 테스트.

파일 검증은 변환과 분리해 유지하십시오. 변환 서비스는 이미 인가된 입력을 받아야 하며, 그래도 심층 방어 수단으로 패키지 검증에 의존해야 합니다.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

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

        return $result->pdfData;
    }
}

변환 패턴

패턴	API	사용 시점	제약 조건
파일 경로 변환	`GotenbergBridge::convertFile()`	문서가 이미 디스크에 저장되어 있는 경우.	경로는 읽을 수 있어야 하며 정책상 승인되어야 합니다.
메모리 내 바이트 변환	`GotenbergBridge::convertString()`	애플리케이션이 업로드 또는 오브젝트 스토어에서 가져온 바이트를 이미 보유하고 있는 경우.	파일 이름이 여전히 형식 감지를 제어합니다.
페이로드 직접 구성	`GotenbergConvertPayload`	테스트나 사용자 지정 전송 코드에서 멀티파트 바이트가 필요한 경우.	경계(boundary) 생성은 사용자 입력과 분리하십시오.
응답 직접 구문 분석	`GotenbergResponseParser::parse()`	사용자 지정 HTTP 호출에서도 패키지의 구문 분석을 사용하려는 경우.	예상되는 `OfficeFormat`을 전달해야 합니다.

상태 및 준비 상태

GotenbergBridge::isAvailable()는 준비 상태 신호입니다. 이를 유일한 런타임 가드로 삼아서는 안 됩니다. 서비스가 준비 상태로 표시되더라도 다음 변환은 실패할 수 있습니다.

점검 항목	용도	운영 참고 사항
구성 유효성	누락된 API URL을 감지합니다.	앱 부팅 또는 배포 점검 중에 실행하십시오.
`/health` 가용성	접근 가능한 서비스를 감지합니다.	준비 상태 대시보드에 사용하십시오.
작은 픽스처 변환	손상된 LibreOffice 또는 서비스 회귀를 감지합니다.	모든 요청마다 실행하지 말고 예약된 스모크 테스트에서 실행하십시오.
타임아웃 모니터링	느린 서비스 동작을 감지합니다.	형식과 파일 크기별로 추적하십시오.

확장 지점

확장 지점	사용 목적	제약 조건
PSR-18 `ClientInterface`	사용자 지정 HTTP 클라이언트 동작.	PSR-18 response/exception 의미 체계를 따라야 합니다.
PSR-17 팩토리	요청 및 스트림 생성.	브리지 구성에 필요합니다.
`HtmlSecurityPolicyInterface`	HTML 입력에 대한 구문 분석 계층 정책.	Gotenberg 보안 정책을 보완합니다.
`ResponseFactoryInterface`	고정된 cURL 전송 응답 구성.	패키지 전송 경로를 사용할 때만 필요합니다.
`GotenbergSecurityPolicy`	URL, 파일 크기, 파일 이름, 핀 검증.	애플리케이션 인가는 이 계층 밖에 두십시오.

개발 워크플로

테스트에서 convertString()으로 시작해 픽스처를 명시적으로 만드십시오.
파일 시스템 경로가 통제된 후에만 convertFile()을 추가하십시오.
최대 파일 크기는 서비스와 인프라 한도보다 낮게 유지하십시오.
준비 상태 신호로는 isAvailable()을(를) 사용하고, 오류 처리의 대체 수단으로 사용하지 마십시오.
파일 이름, 형식, 크기, 상태, 소요 시간을 기록하십시오. 문서 바이트는 기록하지 마십시오.
업로드 엔드포인트를 노출하기 전에 타임아웃과 실패 모드 테스트를 추가하십시오.

실패 처리

실패	처리해야 할 위치	권장 대응
지원되지 않는 확장자	형식 감지.	서비스 디스패치 전에 거부합니다.
안전하지 않은 파일 이름	보안 정책.	거부하고 업로드 이름 지정 정책을 정규화합니다.
크기 초과 파일	업로드 정책 및 패키지 검증.	큰 페이로드를 읽거나 전송하기 전에 거부합니다.
Gotenberg 사용 불가	브리지 경계.	적절한 경우 재시도 가능한 애플리케이션 오류를 반환합니다.
PDF가 아닌 응답	응답 파서.	변환 실패로 처리하고 서비스 상태를 수집합니다.
핀 또는 URL 검증 실패	전송 정책.	안전하게 차단(fail closed)하고 운영자에게 경고합니다.

안전한 기본값

고려 사항	기본값	재정의 시점
타임아웃	`30`초.	실제 서비스 지연 시간을 측정한 후에만 늘리십시오.
최대 파일 크기	`52,428,800`바이트.	공개 또는 멀티테넌트 엔드포인트의 경우 더 낮게 설정하십시오.
API 키	비어 있음.	비공개 Gotenberg 배포의 경우 설정하십시오.
지원되는 형식	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	형식은 `OfficeFormat`과 파서가 지원하는 경우에만 추가하십시오.
핀 세트	비어 있음.	백업 핀과 교체 절차를 함께 갖춘 상태에서 핀을 추가하십시오.

테스트 체크리스트

형식 테스트는 지원되는 확장자와 지원되지 않는 확장자를 모두 다룹니다.
파일 테스트는 누락, 읽기 불가, 크기 초과, 안전하지 않은 파일 이름을 다룹니다.
서비스 테스트는 2xx가 아닌 응답, 잘못된 응답 본문, 전송 예외를 다룹니다.
보안 테스트는 정책이 금지하는 비공개 또는 잘못된 서비스 URL을 다룹니다.
타임아웃 테스트는 구성된 타임아웃이 전송 계층에 전달되는지 검증합니다.
픽스처 테스트는 샘플 문서를 작고 민감하지 않은 상태로 유지합니다.