NextPDF Cloudflare 부트와 디스커버리

한눈에 보기

이 브리지는 자체 서비스 프로바이더나 번들, 자동 디스커버리 훅을 제공하지 않습니다. 명시적 생성자를 갖춘 final 클래스들의 집합입니다. 여기서 “디스커버리”는 어떤 협력 객체를 주입할지 결정하고, 이를 프레임워크 컨테이너에 바인딩하는 과정을 뜻합니다. 이 페이지에서는 그 연결 방식을 설명합니다. 패키지에 없는 등록 메커니즘을 있는 것처럼 꾸며 내지 않습니다.

렌더러 브리지가 디스커버리되는 방식

CloudflareHtmlRenderer는 직접 생성하는 객체이지, 디스커버리되는 객체가 아닙니다. 그 의존성은 PSR-18, PSR-17, PSR-3 인터페이스와 패키지 자체의 구성 및 컨트랙트 타입입니다. 이러한 협력 객체를 구성할 수 있는 프레임워크라면 어떤 프레임워크든 렌더러를 구성할 수 있습니다. 패키지는 PSR 컨트랙트에만 의존하므로 — tests/Unit/Architecture/PsrConformanceTest.php 테스트가 구체 클라이언트와 결합하지 않음을 단언합니다 — 호스트 애플리케이션은 기존 HTTP 클라이언트 바인딩을 그대로 재사용할 수 있습니다. Laravel, Symfony, CodeIgniter용 NextPDF 어댑터는 동일한 PSR-18 바인딩을 재사용합니다. 이 패키지는 자체 프레임워크 패키지를 추가하지 않습니다.

부트 시퀀스

CloudflareHtmlRenderer의 생성자를 그대로 따라 다음 순서로 객체를 해석합니다:

PSR-18 ClientInterface를 해석합니다(애플리케이션의 기존 HTTP 클라이언트 바인딩).
PSR-17 RequestFactoryInterface와 StreamFactoryInterface를 해석합니다. 고정된 cURL 전송을 사용하려면 ResponseFactoryInterface도 해석합니다.
해석된 구성 값으로 CloudflareRendererConfig를 구성합니다(“구성 해석 순서” 참조).
선택적으로 PSR-3 LoggerInterface, LocalRendererFactoryInterface, 명시적으로 지정된 HtmlSecurityPolicyInterface를 해석합니다.
위 객체들로 CloudflareHtmlRenderer를 생성합니다.

어느 단계에서도 네트워크에 접속하지 않습니다. 첫 네트워크 상호작용은 첫 render() 호출 또는 첫 isAvailable() 호출에서 발생합니다.

컨테이너 바인딩

대표적인 바인딩 예시입니다(프레임워크에 종속되지 않는 의사 코드):

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Psr\Log\LoggerInterface;

$container->singleton(CloudflareHtmlRenderer::class, function ($c) {
    return new CloudflareHtmlRenderer(
        config:          CloudflareRendererConfig::fromArray($c->get('config')['cloudflare']),
        httpClient:      $c->get(ClientInterface::class),
        requestFactory:  $c->get(RequestFactoryInterface::class),
        streamFactory:   $c->get(StreamFactoryInterface::class),
        logger:          $c->get(LoggerInterface::class),
        responseFactory: $c->get(ResponseFactoryInterface::class),
    );
});

구성 해석 순서

패키지는 환경 변수를 직접 읽지 않고, 완전히 구성된 CloudflareRendererConfig를 받습니다. 호스트 애플리케이션에서 권장되는 해석 순서는 다음과 같습니다. 먼저 환경 변수, 다음으로 게시된 구성 또는 프레임워크 구성, 마지막으로 생성자에 내장된 패키지 기본값(/integrations/cloudflare/configuration/에 문서화됨)입니다. CloudflareRendererConfig::fromArray()는 누락되었거나 타입이 잘못된 키에 생성자 기본값을 적용하므로, 부분 구성 배열도 실패하지 않고 예측 가능하게 폴백합니다.

진단

부트 시점의 신호는 CloudflareRendererConfig::isValid()입니다 — workerUrl과 apiToken이 모두 비어 있지 않은지 네트워크 호출 없이 확인하는 순수 검사이므로 배포 게이트에 적합합니다. 런타임 신호는 CloudflareHtmlRenderer::isAvailable()입니다. 이는 인증된 HTTP HEAD 요청이며, 상태 코드가 500 미만이면 true를, 그 밖의 경우에는 false를 반환합니다(절대 예외를 던지지 않음). 따라서 준비 상태 프로브에 적합합니다. 프로브 통과는 힌트일 뿐, 보장이 아닙니다. 이어지는 POST는 여전히 실패할 수 있습니다.

함께 보기

/integrations/cloudflare/integration/ — 엔드 투 엔드 통합을 안내합니다.
/integrations/cloudflare/overview/ — 브리지가 무엇인지, 어떤 경계를 넘는지 설명합니다.
/integrations/cloudflare/configuration/ — 모든 필드와 기본값을 설명합니다.
/integrations/cloudflare/security-and-operations/ — 고정된 전송이 활성화되는 시점을 설명합니다.