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 は依然として失敗する可能性があります。

NextPDF Cloudflare のブートとディスカバリー

概要

レンダラーブリッジのディスカバリー方法

ブートシーケンス

コンテナーバインディング

設定の解決順序

診断

関連項目