Интеграция NextPDF с Cloudflare

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

На этой странице показан полный сценарий Cloudflare: установка пакета, его настройка, отрисовка файла Portable Document Format (PDF) и, при необходимости, архивация результата. На каждом шаге отрисовка проходит через Cloudflare Worker и R2. Используйте это практическое руководство вместе с концептуальной страницей /integrations/cloudflare/overview/ и справочной страницей /integrations/cloudflare/configuration/.

Установка

composer require nextpdf/cloudflare:^0.1

Затем добавьте клиент PHP Standards Recommendation (PSR)-18 и фабрики PSR-17, например, Guzzle 7. Пакет объявляет только контракты PSR и не поставляет конкретный клиент, поэтому его нужно предоставить отдельно. Подробные сведения см. на странице /integrations/cloudflare/install/.

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

Мост не включает ни сервис-провайдер, ни бандл. Создайте его напрямую из PSR-коллабораторов и CloudflareRendererConfig. Хост-фреймворк должен зарегистрировать его в своём контейнере, переиспользуя существующую привязку PSR-18 в приложении. Полную последовательность загрузки и пример привязки в контейнере см. на странице /integrations/cloudflare/boot-and-discovery/.

Привязки в контейнере

Зарегистрируйте CloudflareHtmlRenderer как singleton. Передайте клиент PSR-18, фабрики запросов и потоков PSR-17 и, при необходимости, логгер PSR-3. Если вы используете закреплённый транспорт cURL, передайте также фабрику ответов PSR-17. Пример привязки см. на странице /integrations/cloudflare/boot-and-discovery/.

Публикация конфигурации

Пакет читает настройки из CloudflareRendererConfig. Загружайте секреты из переменных окружения, а не из закоммиченных файлов:

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => getenv('CF_WORKER_URL') ?: '',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => getenv('CF_R2_FONT_BUCKET') ?: null,
]);

workerUrl должен использовать схему Hypertext Transfer Protocol Secure (HTTPS). apiToken помечен как #[SensitiveParameter]. Полный справочник по полям см. на странице /integrations/cloudflare/configuration/, где описаны поля закрепления Subject Public Key Info (SPKI) и все значения по умолчанию. Настройка архивации R2 и уровень защиты application programming interface (API) описаны на странице /integrations/cloudflare/production-usage/.

Дымовая проверка сервис-провайдера и бандла

Отдельной дымовой проверки сервис-провайдера нет. Вместо этого используйте следующую проверку при загрузке:

$config = CloudflareRendererConfig::fromArray($appConfig['cloudflare']);
assert($config->isValid(), 'Cloudflare config incomplete');

// Optional runtime reachability check (authenticated HTTP HEAD):
if (!$renderer->isAvailable()) {
    // Worker not reachable — degrade or alert.
}

isValid() — это чистая проверка полноты без сетевых вызовов. isAvailable() выполняет аутентифицированный запрос HEAD. Если Worker недоступен, он возвращает false, не выбрасывая исключения.

Публичные точки входа API

Пакет предоставляет следующий публичный интерфейс в пространстве NextPDF\Cloudflare\:

Тип	Роль
`CloudflareHtmlRenderer`	Точка входа для отрисовки: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Конфигурация средства отрисовки (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Типизированный результат отрисовки (`isValid()`, `size()`).
`CloudflareRenderPayload`	Полезная нагрузка Worker в формате JavaScript Object Notation (JSON) (`toJson()`).
`CloudflareResponseParser`	Парсер ответа Worker → результат.
`CloudflareSecurityPolicy`	Проверка входных данных и URL.
`Transport\PinnedCurlTransport`	Транспорт PSR-18 с закреплением Domain Name System (DNS) / Transport Layer Security (TLS).
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Контракты локального резервного варианта.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Защита входящих запросов API.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	Архивация в R2.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Иерархия исключений.

Полное пошаговое руководство по отрисовке см. на странице /integrations/cloudflare/quickstart/. Сведения о production-настройке см. на странице /integrations/cloudflare/production-usage/, где описаны резервный вариант, телеметрия, архивация и защита.

См. также

/integrations/cloudflare/overview/ — граница доверия и модель отрисовки на периферии.
/integrations/cloudflare/quickstart/ — первая отрисовка, готовая к запуску.
/integrations/cloudflare/boot-and-discovery/ — подробности подключения в контейнере.
/integrations/cloudflare/security-and-operations/ — защита от server-side request forgery (SSRF), закрепление и эксплуатационный runbook.
/integrations/cloudflare/troubleshooting/ — сопоставление режимов сбоев с исключениями.