NextPDF Cloudflare 启动与发现

概览

该桥接本身不附带服务提供者、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/ —— 固定传输何时会激活。