NextPDF-Cloudflare-integratie

In één oogopslag

Deze pagina beschrijft het volledige Cloudflare-traject: installeer het pakket, configureer het, render een Portable Document Format (PDF)-bestand en archiveer desgewenst het resultaat. Bij elke stap loopt de rendering via een Cloudflare Worker en R2. Gebruik deze how-to naast het conceptuele /integrations/cloudflare/overview/ en de referentie /integrations/cloudflare/configuration/.

Installeren

composer require nextpdf/cloudflare:^0.1

Voeg daarna een PHP Standards Recommendation (PSR)-18-client en PSR-17-factory’s toe, zoals Guzzle 7. Het pakket declareert alleen PSR-contracten en levert geen concrete client mee; u levert die zelf aan. Zie /integrations/cloudflare/install/ voor de volledige details.

Boot/auto-discovery

De bridge bevat geen service provider en geen bundle. Construeer de bridge rechtstreeks vanuit PSR-collaborators en een CloudflareRendererConfig. Bind de bridge in de container van uw host-framework door de bestaande PSR-18-binding van de applicatie te hergebruiken. Zie /integrations/cloudflare/boot-and-discovery/ voor de volledige bootvolgorde en een voorbeeld van een container-binding.

Container-bindings

Bind CloudflareHtmlRenderer als singleton. Geef de PSR-18-client, de PSR-17-request- en stream-factory’s en een optionele PSR-3-logger door. Wanneer u het pinned cURL-transport gebruikt, geeft u ook een PSR-17-response-factory door. Zie het voorbeeld van een binding in /integrations/cloudflare/boot-and-discovery/.

Configuratie publiceren

Het pakket leest instellingen uit een CloudflareRendererConfig. Laad secrets uit de omgeving, nooit uit bestanden die zijn gecommit:

<?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 moet het Hypertext Transfer Protocol Secure (HTTPS)-schema gebruiken. apiToken is gemarkeerd met #[SensitiveParameter]. Zie /integrations/cloudflare/configuration/ voor de volledige veldreferentie; die behandelt de Subject Public Key Info (SPKI)-pinvelden en elke standaardwaarde. R2-archiveringsconfiguratie en de beschermingslaag voor de application programming interface (API) worden behandeld in /integrations/cloudflare/production-usage/.

Service-provider/bundle-smoke-test

Er is geen service provider om een smoke-test op uit te voeren. Gebruik in plaats daarvan deze bootcontrole:

$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 een zuivere volledigheidscontrole en doet geen netwerkaanroep. isAvailable() voert een geauthenticeerde HEAD uit. De methode retourneert false zonder een exception te gooien als de Worker offline is.

Publieke API-entrypoints

Het pakket biedt dit publieke oppervlak aan onder NextPDF\Cloudflare\:

Type	Rol
`CloudflareHtmlRenderer`	Render-entrypoint: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Renderer-configuratie (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Getypeerd renderresultaat (`isValid()`, `size()`).
`CloudflareRenderPayload`	Worker JavaScript Object Notation (JSON)-payload (`toJson()`).
`CloudflareResponseParser`	Worker-response → resultaatparser.
`CloudflareSecurityPolicy`	Validatie van invoer en URL’s.
`Transport\PinnedCurlTransport`	PSR-18-transport met Pinned Domain Name System (DNS) / Transport Layer Security (TLS)-pinning.
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Contracten voor lokale fallback.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Inkomende API-bescherming.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	R2-archivering.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Exception-hiërarchie.

Zie /integrations/cloudflare/quickstart/ voor een volledige render-walkthrough. Zie /integrations/cloudflare/production-usage/ voor de wiring in productie; daarin worden fallback, telemetrie, archivering en bescherming behandeld.

Zie ook

/integrations/cloudflare/overview/ — de trust boundary en het edge-renderingmodel.
/integrations/cloudflare/quickstart/ — een uitvoerbare eerste render.
/integrations/cloudflare/boot-and-discovery/ — details over container-wiring.
/integrations/cloudflare/security-and-operations/ — bescherming tegen server-side request forgery (SSRF), pinning en het operationele runbook.
/integrations/cloudflare/troubleshooting/ — faalmodi die aan exceptions zijn gekoppeld.