Konfiguracja mostka Cloudflare w NextPDF

W skrócie

Pakiet korzysta z trzech niemutowalnych obiektów konfiguracji. Każda wartość domyślna na tej stronie pochodzi z odpowiadającej jej sygnatury konstruktora w src/Cloudflare/. Nie pochodzi ze specyfikacji ani z szacunków. Tam, gdzie ta strona podaje maksimum, jest to limit, który egzekwuje ten pakiet. Nie jest to informacja o przepustowości platformy Cloudflare.

`CloudflareRendererConfig`

Konfiguracja rendera. final readonly. Można ją utworzyć bezpośrednio albo za pomocą CloudflareRendererConfig::fromArray().

Pole	Typ	Domyślnie	Znaczenie
`workerUrl`	`string`	— (wymagane)	Adres URL punktu końcowego Workera. Musi być HTTPS.
`apiToken`	`string`	— (wymagane)	Token typu Bearer. Oznaczony jako `#[SensitiveParameter]`.
`renderTimeout`	`int`	`30`	Limit czasu transferu w sekundach, stosowany przez przypięty transport cURL.
`defaultCss`	`string`	`''`	CSS wstrzykiwany do ładunku przed kodem HTML.
`maxHtmlSize`	`int`	`5000000`	Maksymalny rozmiar danych wejściowych HTML w bajtach, egzekwowany przed wysłaniem żądania.
`r2FontBucket`	`?string`	`null`	Nazwa zasobnika R2 na niestandardowe pakiety czcionek.
`fallbackToLocal`	`bool`	`true`	Określa, czy nieosiągalny Worker przełącza się na lokalny render.
`pinnedPublicKeys`	`list<string>`	`[]`	Odciski palca SPKI SHA-256, w formacie `sha256/<base64>`.
`backupPublicKeys`	`list<string>`	`[]`	Zapasowe przypięcia SPKI, trzymane osobno, aby rotacja była weryfikowana niezależnie.

isValid() zwraca true tylko wtedy, gdy workerUrl !== '' oraz apiToken !== ''. allPublicKeyPins() zwraca sumę zbiorów pinnedPublicKeys oraz backupPublicKeys, bez duplikatów. Warstwa TLS akceptuje certyfikat, którego skrót SPKI występuje w dowolnym elemencie tej sumy. Jest to zgodne z RFC 7469 §2.6, który uznaje przypięte połączenie za prawidłowe, gdy zbiór przedstawionych odcisków palca SPKI przecina się ze zbiorem przypiętym. RFC 7469 §2.5 opisuje przypięcie zapasowe jako podstawowy mechanizm odzyskiwania na wypadek niezamierzonego niepowodzenia walidacji przypięcia. Zachowaj co najmniej jedno przypięcie zapasowe, aby rotacja certyfikatu nie uszkodziła punktu końcowego — zobacz /integrations/cloudflare/security-and-operations/.

Mapa kluczy `fromArray()`

CloudflareRendererConfig::fromArray() odczytuje klucze w formacie snake_case i stosuje te same wartości domyślne, gdy klucza brakuje albo ma niewłaściwy typ:

Klucz tablicy	Mapuje się na
`worker_url`	`workerUrl`
`api_token`	`apiToken`
`render_timeout`	`renderTimeout` (domyślnie `30`)
`default_css`	`defaultCss`
`max_html_size`	`maxHtmlSize` (domyślnie `5000000`)
`r2_font_bucket`	`r2FontBucket`
`fallback_to_local`	`fallbackToLocal` (domyślnie `true`)
`pinned_public_keys`	`pinnedPublicKeys` (elementy niebędące łańcuchami znaków są pomijane)
`backup_public_keys`	`backupPublicKeys` (elementy niebędące łańcuchami znaków są pomijane)

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => 'https://pdf-renderer.example.workers.dev/render',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => 'pdf-fonts',
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Limity rozmiaru danych wejściowych egzekwowane przez pakiet

Te limity egzekwuje CloudflareSecurityPolicy::validate(), zanim jakiekolwiek żądanie opuści proces. Liczby są odczytywane ze źródła:

Limit	Wartość	Gdzie
Maksymalne dane wejściowe HTML	`maxHtmlSize` (domyślnie `5000000` bajtów)	`CloudflareSecurityPolicy::validate()`
Maksymalny rozmiar zdekodowanego identyfikatora URI danych base64	`13631488` bajtów (≈13 MB)	`CloudflareSecurityPolicy::MAX_DATA_URI_BYTES`

Przekroczenie któregokolwiek z nich powoduje zgłoszenie RuntimeException z komunikatem podającym niedozwolony rozmiar oraz limit. Pułap base64 zabezpiecza przed bombą dekompresyjną. Polityka szacuje rozmiar zdekodowanych danych na podstawie długości base64 i odrzuca je po osiągnięciu pułapu albo jego przekroczeniu. Znacznik <meta http-equiv="refresh"> również jest odrzucany, bez rozróżniania wielkości liter, ponieważ może wywołać przekierowanie z wnętrza renderowanej strony.

Pakiet podaje wyłącznie limity, które sam egzekwuje. Nie formułuje żadnych twierdzeń o właściwych Workerowi limitach żądań, procesora ani pamięci. Zajrzyj w tym celu do oficjalnej dokumentacji Cloudflare oraz do implementacji swojego Workera.

`ApiProtectionConfig`

Konfiguracja opcjonalnej warstwy ochrony żądań, którą Worker — albo bramka PHP umieszczona przed nim — stosuje do przychodzących żądań renderowania. final readonly.

Pole	Typ	Domyślnie	Znaczenie
`maxRequestsPerMinute`	`int`	`60`	Limit żądań na klienta na minutę.
`maxRequestsPerHour`	`int`	`1000`	Limit żądań na klienta na godzinę.
`maxPayloadSizeBytes`	`int`	`10485760`	Maksymalny ładunek przychodzący (≈10 MB).
`allowedOrigins`	`list<string>`	`[]`	Lista dozwolonych źródeł CORS. Pusta oznacza, że nie zdefiniowano tu żadnego ograniczenia źródła.
`requireApiKey`	`bool`	`true`	Określa, czy klucz API jest wymagany.
`apiKeyHeader`	`string`	`'X-Api-Key'`	Nagłówek przenoszący klucz API.
`rateLimitWindowSeconds`	`int`	`60`	Długość okna na minutę, w sekundach.

fromArray() odczytuje max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header oraz rate_limit_window_seconds. isValid() wymaga, aby każde pole liczbowe było dodatnie, a apiKeyHeader — niepuste.

`R2ArchiveConfig`

Konfiguracja archiwizacji renderowanych plików PDF w Cloudflare R2 przez interfejs API zgodny z S3. final readonly.

Pole	Typ	Domyślnie	Znaczenie
`bucketName`	`string`	— (wymagane)	Zasobnik R2. Walidowany według reguły nazewnictwa S3.
`accountId`	`string`	— (wymagane)	Identyfikator konta Cloudflare, używany do zbudowania domyślnego punktu końcowego.
`accessKeyId`	`string`	— (wymagane)	Identyfikator klucza dostępu R2. `#[SensitiveParameter]`.
`secretAccessKey`	`string`	— (wymagane)	Tajny klucz dostępu R2. `#[SensitiveParameter]`.
`endpoint`	`string`	`''`	Niestandardowy punkt końcowy S3. Pusty buduje wartość domyślną na podstawie `accountId`.
`pathPrefix`	`string`	`'pdfs/'`	Prefiks klucza przesyłanych obiektów.
`maxFileSizeBytes`	`int`	`104857600`	Maksymalny rozmiar przesyłanego pliku (≈100 MB), egzekwowany przed przesłaniem.

Konstruktor odrzuca niepuste bucketName, które nie pasuje do reguły zgodnej z S3. Reguła ta wymaga od 3–63 znaków, małych liter alfanumerycznych oraz łączników, z początkiem i końcem na znaku alfanumerycznym. Naruszenie powoduje zgłoszenie InvalidArgumentException. isValid() wymaga, aby bucketName, accountId, accessKeyId oraz secretAccessKey były niepuste. Gdy endpoint jest pusty, getEndpoint() zwraca https://<accountId>.r2.cloudflarestorage.com.

Obsługa danych poufnych

apiToken, accessKeyId oraz secretAccessKey mają atrybut #[SensitiveParameter], więc PHP usuwa je ze śladów stosu. Przekazuj je przez zmienne środowiskowe lub menedżera danych poufnych. Nigdy nie umieszczaj ich w repozytorium. Obiekty konfiguracji są niemutowalne, więc raz ustawionej wartości nie można zmienić po utworzeniu.

Zobacz także

/integrations/cloudflare/quickstart/ — zastosuj tę konfigurację przy pierwszym renderze.
/integrations/cloudflare/production-usage/ — przełączanie awaryjne, archiwizacja R2 oraz ochrona API połączone w jedną całość.
/integrations/cloudflare/security-and-operations/ — przypinanie, obrona przed SSRF oraz rotacja danych poufnych.

Konfiguracja mostka Cloudflare w NextPDF

W skrócie

CloudflareRendererConfig

Mapa kluczy fromArray()