NextPDF Cloudflare 的啟動與探索

概覽

這個橋接器本身不隨附任何 service provider、bundle，也沒有自己的自動探索掛鉤。它是一組具備明確建構子的 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/ — 釘選傳輸何時會啟用。