Загрузка и обнаружение в NextPDF Cloudflare

Краткий обзор

Мост не содержит ни собственного провайдера сервисов, ни bundle, ни хука для автообнаружения. Это набор final-классов с явными конструкторами. Здесь “обнаружение” означает выбор внедряемых зависимостей и их привязку в контейнере вашего фреймворка. На этой странице описана именно такая связка. Она не вводит механизм регистрации, которого в пакете нет.

Как обнаруживается мост рендерера

Вы создаёте CloudflareHtmlRenderer, а не обнаруживаете его. Его зависимости — это контракты PHP Standard Recommendation (PSR): PSR-18, PSR-17 и PSR-3, а также собственные типы конфигурации и контрактов пакета. Любой фреймворк, способный создать эти зависимости, может создать рендерер. Пакет зависит только от контрактов PSR; тест tests/Unit/Architecture/PsrConformanceTest.php проверяет, что рендерер не привязан ни к одному конкретному клиенту. Хост-приложение может без изменений использовать уже существующую привязку HTTP-клиента. Адаптеры NextPDF для Laravel, Symfony и CodeIgniter повторно используют ту же привязку PSR-18. Этот пакет не добавляет собственного пакета для фреймворка.

Последовательность загрузки

Разрешайте зависимости в порядке, соответствующем конструктору CloudflareHtmlRenderer:

1. Разрешите ClientInterface PSR-18 из имеющейся в приложении привязки HTTP-клиента.
2. Разрешите RequestFactoryInterface и StreamFactoryInterface PSR-17; также разрешите ResponseFactoryInterface, если вам нужен закреплённый транспорт cURL.
3. Соберите CloudflareRendererConfig из разрешённой конфигурации (см. “Порядок разрешения конфигурации”).
4. При необходимости разрешите LoggerInterface PSR-3, LocalRendererFactoryInterface и явный HtmlSecurityPolicyInterface.
5. Создайте 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, который возвращает true для статуса ниже 500 и false (никогда не выбрасывая исключение) в противном случае, поэтому его можно использовать как проверку готовности. Успешная проверка — это подсказка, а не гарантия: последующий POST всё равно может завершиться неудачей.

См. также

• /integrations/cloudflare/integration/ — полное пошаговое руководство по интеграции.
• /integrations/cloudflare/overview/ — что такое мост и какую границу он пересекает.
• /integrations/cloudflare/configuration/ — каждое поле и значение по умолчанию.
• /integrations/cloudflare/security-and-operations/ — когда активируется закреплённый транспорт.