NextPDF Gotenberg 빠른 시작

한눈에 보기

이 가이드에서는 하나의 .docx 파일을 PDF로 변환합니다. 끝까지 따라 하면 세 가지 결과를 얻습니다. 동작하는 브리지 인스턴스, 검증된 서비스 연결, 디스크에 저장된 PDF입니다. 전체 프로그램은 저장소의 examples/convert-office-to-pdf.php에 있습니다. 아래 코드 조각들은 해당 프로그램에서 발췌한 것입니다.

이 페이지는 튜토리얼이므로 정상 동작 경로를 먼저 보여 줍니다. 프로덕션에서 고려해야 하는 비밀 정보 관리, 재시도, 타임아웃, 관측성은 /integrations/gotenberg/production-usage/ 페이지에서 다룹니다.

시작하기 전에

다음 세 가지를 확인해야 합니다.

composer require nextpdf/gotenberg를 실행했고, PSR-18 클라이언트와 PSR-17 팩토리가 설치되어 있어야 합니다. 자세한 내용은 /integrations/gotenberg/install/ 페이지를 참고합니다.
Gotenberg 서비스에 HTTPS로 접근할 수 있어야 합니다. 일반 http:// 요청은 프로세스를 떠나기 전에 브리지가 모두 거부합니다.
다음 형식 중 하나인 샘플 파일이 있어야 합니다. .docx, .xlsx, .pptx, .odt, .ods, 또는 .odp. 다른 확장자는 ValueError로 거부됩니다.

1 단계 — 서비스 설명하기

GotenbergConfig는 불변 값 객체입니다. 최소한 Gotenberg 서비스의 HTTPS 기본 URL이 필요합니다.

use NextPDF\Gotenberg\GotenbergConfig;

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

timeout은 초 단위 전송 타임아웃으로, cURL 고정 전송 계층에서 적용합니다. apiKey는 비어 있지 않을 때 Authorization: Bearer <token>로 전송됩니다. Gotenberg 배포가 토큰을 요구하지 않는다면 apiKey를 비워 둡니다.

2 단계 — 브리지 연결하기

브리지는 구성과 해당 PSR 협력 객체를 받습니다. DNS 고정과 TLS 고정이 적용된 cURL 전송 계층을 활성화하려면 responseFactory도 주입합니다.

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

브리지는 HTTP 클라이언트를 직접 생성하지 않습니다. 설치해 둔 어떤 PSR-18 클라이언트와 PSR-17 팩토리든 사용할 수 있습니다. 예제 파일에는 Guzzle 연결 예시가 주석으로 들어 있습니다.

3 단계 — 가용성 확인하기

무언가를 변환하기 전에 서비스를 점검합니다. 이 점검은 먼저 네트워크 트래픽 없이 URL을 검증한 다음, <apiUrl>/health로 HEAD를 전송합니다.

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

isAvailable()는 비어 있거나 HTTPS가 아니거나 사설 주소인 URL, 그리고 모든 네트워크 오류에 대해 false를 반환합니다(절대 예외를 던지지 않습니다). /health에서 500 미만의 상태 코드는 서비스를 사용할 수 있음을 의미합니다.

4 단계 — 변환하기

convertFile()은 디스크에 있는 파일 경로를 받습니다. 경로는 순회 공격을 차단하기 위해 정규화됩니다. 확장자는 지원되는 형식으로 매핑됩니다. 크기와 파일 이름이 검사됩니다. 그런 다음 멀티파트 요청이 <apiUrl>/forms/libreoffice/convert로 전송됩니다.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

이미 메모리에 있는 바이트를 변환하려면 convertString()을 사용합니다. 브리지가 확장자를 감지할 수 있도록 원래 파일 이름을 전달합니다.

$pdf = $bridge->convertString($docxBytes, 'report.docx');

5 단계 — 결과 사용하기

결과에는 세 가지가 담겨 있습니다. PDF 바이트, 원본 형식, 유효성 검사 결과입니다.

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

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

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

isValid()는 본문이 비어 있지 않고 %PDF로 시작할 때 true입니다. size()는 바이트 길이입니다. 이 시점부터 PDF는 후처리를 위해 NextPDF에 넘길 수 있는 일반 스트림입니다.

완전한 프로그램

완전히 실행 가능한 프로그램은 패키지 저장소의 examples/convert-office-to-pdf.php에 있습니다. 여기에는 인수 파싱, 환경 변수 기반 구성, 헬스 점검, 빠짐없는 오류 처리, 쓰기까지 포함되어 있습니다. 다음 명령으로 실행합니다.

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

다음 단계

/integrations/gotenberg/configuration/ — 모든 옵션과 전송 계층 선택 규칙.
/integrations/gotenberg/production-usage/ — 비밀 정보, 재시도, 타임아웃, 로깅, 동시성.
/integrations/gotenberg/troubleshooting/ — 이 코드가 던질 수 있는 모든 예외와 그 의미.
/integrations/gotenberg/integration/ — 서비스를 통해 NextPDF 렌더링 파이프라인 구동하기.