NextPDF Cloudflare 통합

한눈에 보기

이 페이지는 처음부터 끝까지 이어지는 전체 과정을 다룹니다. 패키지를 설치하고 구성한 뒤 PDF를 렌더링하고, 필요한 경우 결과를 보관합니다. 각 단계에서는 Cloudflare Worker와 R2를 통해 NextPDF 렌더링을 구동합니다. 이 문서는 개념 설명인 /integrations/cloudflare/overview/와 레퍼런스인 /integrations/cloudflare/configuration/를 함께 다루는 실습 안내서입니다.

설치

composer require nextpdf/cloudflare:^0.1

다음으로 Guzzle 7과 같은 PSR-18 클라이언트와 PSR-17 팩토리를 추가합니다. 이 패키지는 PSR 계약만 선언하고 자체적인 클라이언트 구현체를 포함하지 않으므로, 사용자가 직접 제공해야 합니다. 자세한 내용은 /integrations/cloudflare/install/를 참조하십시오.

부트/자동 검색

이 브리지에는 서비스 프로바이더나 번들이 없습니다. 대신 PSR 협력 객체와 CloudflareRendererConfig에서 직접 생성합니다. 호스트 프레임워크는 애플리케이션의 기존 PSR-18 바인딩을 재사용해 자체 컨테이너에 바인딩합니다. 전체 부트 시퀀스와 샘플 컨테이너 바인딩은 /integrations/cloudflare/boot-and-discovery/를 참조하십시오.

컨테이너 바인딩

CloudflareHtmlRenderer를 싱글턴으로 바인딩합니다. 이때 PSR-18 클라이언트, PSR-17 요청 및 스트림 팩토리, 선택적 PSR-3 로거를 전달합니다. 고정된(pinned) cURL 트랜스포트를 사용할 때는 PSR-17 응답 팩토리도 함께 전달합니다. 바인딩 예제는 /integrations/cloudflare/boot-and-discovery/를 참조하십시오.

설정 게시

이 패키지는 CloudflareRendererConfig에서 설정을 읽어 들입니다. 시크릿은 커밋된 파일이 아니라 항상 환경에서 가져오십시오.

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => getenv('CF_WORKER_URL') ?: '',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => getenv('CF_R2_FONT_BUCKET') ?: null,
]);

workerUrl은 HTTPS여야 합니다. apiToken은 #[SensitiveParameter]입니다. 전체 필드 레퍼런스는 /integrations/cloudflare/configuration/를 참조하십시오. 해당 문서에서는 SPKI 핀 필드와 모든 기본값을 다룹니다. R2 보관 구성과 API 보호 계층은 /integrations/cloudflare/production-usage/에서 다룹니다.

서비스 프로바이더/번들 스모크 테스트

스모크 테스트 대상 서비스 프로바이더는 없습니다. 이에 상응하는 부트 점검은 다음과 같습니다.

$config = CloudflareRendererConfig::fromArray($appConfig['cloudflare']);
assert($config->isValid(), 'Cloudflare config incomplete');

// Optional runtime reachability check (authenticated HTTP HEAD):
if (!$renderer->isAvailable()) {
    // Worker not reachable — degrade or alert.
}

isValid()는 네트워크 호출이 없는 순수한 완전성 점검입니다. isAvailable()는 인증된 HEAD 요청을 수행합니다. Worker가 다운된 경우에는 예외를 던지지 않고 false를 반환합니다.

공개 API 진입점

이 패키지의 공개 API 표면은 모두 NextPDF\Cloudflare\ 아래에 있습니다.

유형	역할
`CloudflareHtmlRenderer`	렌더링 진입점: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	렌더러 구성 (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	타입이 지정된 렌더링 결과 (`isValid()`, `size()`).
`CloudflareRenderPayload`	Worker JSON 페이로드 (`toJson()`).
`CloudflareResponseParser`	Worker 응답 → 결과 파서.
`CloudflareSecurityPolicy`	입력 및 URL 검증.
`Transport\PinnedCurlTransport`	고정 DNS / TLS 고정 PSR-18 트랜스포트.
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	로컬 폴백 계약.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	인바운드 API 보호.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	R2 보관.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	예외 계층 구조.

전체 렌더링 과정에 대한 안내는 /integrations/cloudflare/quickstart/를 참조하십시오. 프로덕션 연결 구성은 /integrations/cloudflare/production-usage/에서 다루며, 폴백, 텔레메트리, 보관, 보호를 포함합니다.

함께 보기

/integrations/cloudflare/overview/ — 신뢰 경계와 엣지 렌더링 모델.
/integrations/cloudflare/quickstart/ — 실행 가능한 첫 렌더링.
/integrations/cloudflare/boot-and-discovery/ — 컨테이너 연결 구성의 세부 정보.
/integrations/cloudflare/security-and-operations/ — SSRF 방어, 고정(pinning), 운영 런북.
/integrations/cloudflare/troubleshooting/ — 예외에 매핑된 실패 모드.