Быстрый старт: первая отрисовка на периферии

Кратко

На этой странице вы преобразуете одну строку Hypertext Markup Language (HTML) в файл Portable Document Format (PDF). Каждый вызов соответствует методу, а поведение каждого метода проверяется в tests/Unit/Cloudflare/CloudflareHtmlRendererTest.php.

Предварительные требования

• Конечная точка Worker, которая обслуживает контракт отрисовки по Hypertext Transfer Protocol Secure (HTTPS).
• Bearer-токен, принимаемый Worker.
• Клиент PHP Standards Recommendation 18 (PSR-18) и фабрики PHP Standards Recommendation 17 (PSR-17), доступные в путях загрузки (см. /integrations/cloudflare/install/).

Контракт Worker в представлении CloudflareResponseParser: при успешном выполнении он возвращает Hypertext Transfer Protocol (HTTP) 200. Ответ содержит либо Content-Type: application/pdf (необработанные байты PDF), либо Content-Type: application/json с полем pdf в base64. Любой статус, отличный от 200, а также любое тело ответа, не начинающееся с маркера %PDF, трактуется как сбой.

Шаг 1 — создание конфигурации

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = new CloudflareRendererConfig(
    workerUrl: 'https://pdf-renderer.example.workers.dev/render',
    apiToken: getenv('CF_PDF_TOKEN') ?: throw new RuntimeException('CF_PDF_TOKEN not set'),
);

Токен берётся из окружения и никогда не задаётся прямо в коде. workerUrl должен использовать HTTPS. Если передать URL вида http://, мост отклонит его с сообщением Worker URL must use HTTPS ещё до отправки какого-либо запроса.

Шаг 2 — создание модуля отрисовки

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use NextPDF\Cloudflare\CloudflareHtmlRenderer;

$httpFactory = new HttpFactory();

$renderer = new CloudflareHtmlRenderer(
    config:          $config,
    httpClient:      new Client(),     // PSR-18 ClientInterface
    requestFactory:  $httpFactory,     // PSR-17 RequestFactoryInterface
    streamFactory:   $httpFactory,     // PSR-17 StreamFactoryInterface
    logger:          null,             // optional PSR-3 LoggerInterface
    responseFactory: $httpFactory,     // PSR-17; enables the pinned transport
);

Конструктору нужны четыре аргумента: конфигурация, клиент PSR-18, фабрика запросов и фабрика потоков. Ещё четыре аргумента необязательны: логгер, фабрика локального модуля отрисовки, явная политика безопасности HTML и фабрика ответов. Передача фабрики ответов включает закреплённый транспорт client URL (cURL), если задан набор разрешённых адресов Internet Protocol (IP) или набор закреплений Subject Public Key Info (SPKI) (см. /integrations/cloudflare/security-and-operations/).

Шаг 3 — отрисовка и запись

use NextPDF\Cloudflare\Exception\CloudflareNotAvailableException;
use NextPDF\Cloudflare\Exception\CloudflareRenderException;

try {
    $result = $renderer->render('<h1>Hello from the edge</h1>');

    if (!$result->isValid()) {
        throw new RuntimeException('Worker did not return a valid PDF');
    }

    file_put_contents('output.pdf', $result->pdfData);
    printf("Wrote %d bytes from edge %s in %.1f ms\n",
        $result->size(),
        $result->renderLocation !== '' ? $result->renderLocation : 'unknown',
        $result->renderTimeMs,
    );
} catch (CloudflareRenderException $e) {
    // Worker answered but the render failed (HTTP error or malformed body).
    fwrite(STDERR, 'Render failed: ' . $e->getMessage() . PHP_EOL);
    exit(1);
} catch (CloudflareNotAvailableException $e) {
    // Worker unreachable and no usable fallback.
    fwrite(STDERR, 'Edge unavailable: ' . $e->getMessage() . PHP_EOL);
    exit(2);
}

render() по умолчанию использует ширину A4 (595.28 пункта PDF) и автоматически определяемую высоту (heightPt: 0). Два типа исключений разделены намеренно. CloudflareRenderException — это сбой на стороне Worker, и для него не выполняется повтор через резервный механизм. CloudflareNotAvailableException означает, что периферия недоступна, а локальный резервный механизм тоже недоступен.

Шаг 4 — анализ результата

CloudflareRenderResult объявлен как final readonly. Приведённые ниже поля заполняются из заголовков ответа на бинарном пути или из полей JavaScript Object Notation (JSON) на JSON-пути.

Член	Источник
pdfData	Необработанные байты PDF
widthPt	Запрошенная ширина
heightPt	Заголовок X-Pdf-Height-Pt / JSON heightPt; по умолчанию 841.89 (высота A4), если отсутствует или не положительна
contentHeightPx	X-Content-Height-Px / JSON contentHeightPx
renderLocation	Берётся из суффикса заголовка CF-Ray (бинарный путь) или JSON renderLocation
renderTimeMs	X-Render-Time-Ms / JSON renderTimeMs
size()	strlen($pdfData)
isValid()	true, когда байты начинаются с %PDF

Дополнительно — собственный размер бумаги, шрифты, CSS

$result = $renderer->render(
    html:     '<div style="font-family: NotoSansCJK;">繁體中文文件</div>',
    widthPt:  595.28,
    heightPt: 841.89,           // explicit A4; 0 lets the Worker auto-detect
    fontFiles: ['NotoSansCJKtc-Regular.ttf'],
);

fontFiles имеет смысл, только когда в конфигурации задан r2FontBucket. Тогда полезная нагрузка содержит имя бакета и запрошенные пути к файлам шрифтов, чтобы Worker мог их загрузить.

Дополнительно — проверка доступности

if ($renderer->isAvailable()) {
    $result = $renderer->render($html);
}

isAvailable() отправляет аутентифицированный HTTP-запрос HEAD на URL Worker. Метод возвращает true, когда статус ниже 500. Он возвращает false, не выбрасывая исключение, когда конфигурация недопустима или запрос завершается сбоем. Воспринимайте это как подсказку, а не гарантию. Последующий POST к Worker всё равно может завершиться сбоем.

См. также

• /integrations/cloudflare/production-usage/ — подключение резервного механизма, телеметрия и архивирование в R2.
• /integrations/cloudflare/troubleshooting/ — каждый сбой соотнесён со своим исключением и сообщением.
• /integrations/cloudflare/configuration/ — полный справочник по полям.