NextPDF Cloudflare integration

At a glance

This page shows the full Cloudflare path: install the package, configure it, render a Portable Document Format (PDF) file, and optionally archive the result. Each step sends rendering through a Cloudflare Worker and R2. Use this how-to with the conceptual /integrations/cloudflare/overview/ and the reference /integrations/cloudflare/configuration/.

Install

composer require nextpdf/cloudflare:^0.1

Next, add a PHP Standards Recommendation (PSR)-18 client and PSR-17 factories, such as Guzzle 7. The package declares only PSR contracts and includes no concrete client, so you provide one. For the full details, see /integrations/cloudflare/install/.

Boot/auto-discovery

The bridge includes no service provider and no bundle. Construct it directly from PSR collaborators and a CloudflareRendererConfig. Your host framework should bind it in its container by reusing the application’s existing PSR-18 binding. For the full boot sequence and a sample container binding, see /integrations/cloudflare/boot-and-discovery/.

Container bindings

Bind CloudflareHtmlRenderer as a singleton. Pass the PSR-18 client, the PSR-17 request and stream factories, and an optional PSR-3 logger. When you use the pinned cURL transport, also pass a PSR-17 response factory. See the binding example in /integrations/cloudflare/boot-and-discovery/.

Publish config

The package reads settings from a CloudflareRendererConfig. Load secrets from the environment, never from committed files:

<?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 must use the Hypertext Transfer Protocol Secure (HTTPS) scheme. apiToken is #[SensitiveParameter]. For the full field reference, see /integrations/cloudflare/configuration/, which covers the Subject Public Key Info (SPKI) pin fields and every default. R2 archival configuration and the application programming interface (API) protection layer are covered in /integrations/cloudflare/production-usage/.

Service-provider/bundle smoke test

There is no service provider to smoke-test. Use this boot check instead:

$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() is a pure completeness check and makes no network call. isAvailable() performs an authenticated HEAD. It returns false without throwing when the Worker is down.

Public API entry points

The package exposes this public surface under NextPDF\Cloudflare\:

Type	Role
`CloudflareHtmlRenderer`	Render entry point: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Renderer configuration (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Typed render result (`isValid()`, `size()`).
`CloudflareRenderPayload`	Worker JavaScript Object Notation (JSON) payload (`toJson()`).
`CloudflareResponseParser`	Worker response → result parser.
`CloudflareSecurityPolicy`	Input and URL validation.
`Transport\PinnedCurlTransport`	Pinned Domain Name System (DNS) / Transport Layer Security (TLS)-pinned PSR-18 transport.
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Local fallback contracts.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Inbound API protection.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	R2 archival.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Exception hierarchy.

For a complete render walkthrough, see /integrations/cloudflare/quickstart/. For production wiring, see /integrations/cloudflare/production-usage/, which covers fallback, telemetry, archival, and protection.