Integracja NextPDF z Cloudflare

W skrócie

Ta strona przedstawia pełną ścieżkę pracy z Cloudflare: instalację pakietu, konfigurację, renderowanie pliku w formacie Portable Document Format (PDF) oraz opcjonalną archiwizację wyniku. Każdy krok kieruje renderowanie przez Cloudflare Worker oraz R2. Korzystaj z tego poradnika razem z artykułem koncepcyjnym /integrations/cloudflare/overview/ i dokumentacją referencyjną /integrations/cloudflare/configuration/.

Instalacja

composer require nextpdf/cloudflare:^0.1

Następnie dodaj klienta zgodnego z PHP Standards Recommendation (PSR)-18 oraz fabryki zgodne z PSR-17, na przykład Guzzle 7. Pakiet deklaruje wyłącznie kontrakty PSR i nie zawiera implementacji konkretnego klienta, więc trzeba ją dostarczyć samodzielnie. Pełne informacje znajdziesz w /integrations/cloudflare/install/.

Inicjalizacja / automatyczne wykrywanie

Most nie zawiera żadnego dostawcy usług ani pakietu (bundle). Utwórz go bezpośrednio na podstawie zależności PSR oraz obiektu CloudflareRendererConfig. Framework hosta powinien zarejestrować go w swoim kontenerze, ponownie wykorzystując istniejące w aplikacji powiązanie PSR-18. Pełną sekwencję inicjalizacji i przykładowe powiązanie w kontenerze znajdziesz w /integrations/cloudflare/boot-and-discovery/.

Powiązania w kontenerze

Zarejestruj CloudflareHtmlRenderer jako singleton. Przekaż klienta PSR-18, fabryki żądań i strumieni PSR-17 oraz opcjonalny rejestrator zdarzeń PSR-3. Jeśli używasz transportu cURL z przypiętym certyfikatem, przekaż dodatkowo fabrykę odpowiedzi PSR-17. Przykład powiązania znajdziesz w /integrations/cloudflare/boot-and-discovery/.

Publikowanie konfiguracji

Pakiet odczytuje ustawienia z obiektu CloudflareRendererConfig. Wczytuj sekrety ze środowiska, nigdy z plików zapisanych w repozytorium:

<?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 musi używać schematu Hypertext Transfer Protocol Secure (HTTPS). apiToken jest oznaczony jako #[SensitiveParameter]. Pełny opis pól znajdziesz w /integrations/cloudflare/configuration/, gdzie omówiono pola dotyczące przypięcia Subject Public Key Info (SPKI) oraz wszystkie wartości domyślne. Konfigurację archiwizacji R2 i warstwę ochrony API omówiono w /integrations/cloudflare/production-usage/.

Test poprawności dostawcy usług / pakietu

Nie ma dostawcy usług, który można by przetestować pod kątem poprawności. Zamiast tego użyj poniższego sprawdzenia podczas inicjalizacji:

$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() sprawdza wyłącznie kompletność i nie wykonuje żadnego wywołania sieciowego. isAvailable() wykonuje uwierzytelnione żądanie HEAD. Jeśli Worker jest niedostępny, zwraca false i nie zgłasza wyjątku.

Publiczne punkty wejścia API

Pakiet udostępnia następujący publiczny interfejs w przestrzeni NextPDF\Cloudflare\:

Typ	Rola
CloudflareHtmlRenderer	Punkt wejścia do renderowania: render(), isAvailable(), getHtmlSecurityPolicy().
CloudflareRendererConfig	Konfiguracja renderera (fromArray(), isValid(), allPublicKeyPins()).
CloudflareRenderResult	Typowany wynik renderowania (isValid(), size()).
CloudflareRenderPayload	Ładunek Workera w formacie JavaScript Object Notation (JSON) (toJson()).
CloudflareResponseParser	Parser przekształcający odpowiedź Workera → wynik.
CloudflareSecurityPolicy	Walidacja danych wejściowych i adresów URL.
Transport\PinnedCurlTransport	Transport PSR-18 z przypiętym systemem nazw domen (Domain Name System, DNS) i przypiętym certyfikatem Transport Layer Security (TLS).
Contract\LocalRendererFactoryInterface, Contract\LocalRendererInterface	Kontrakty lokalnego mechanizmu awaryjnego.
ApiProtection, ApiProtectionConfig, ApiProtectionResult, ApiKeyValidator	Ochrona przychodzących żądań API.
R2ArchiveManager, R2ArchiveConfig, R2ObjectKey, R2UploadResult	Archiwizacja w R2.
Exception\CloudflareRenderException, Exception\CloudflareNotAvailableException, Exception\InvalidSpkiPinException	Hierarchia wyjątków.

Pełny przewodnik po renderowaniu znajdziesz w /integrations/cloudflare/quickstart/. Łączenie komponentów w środowisku produkcyjnym opisuje /integrations/cloudflare/production-usage/, gdzie omówiono mechanizm awaryjny, telemetrię, archiwizację i ochronę.

Zobacz także

• /integrations/cloudflare/overview/ — granica zaufania i model renderowania na brzegu sieci.
• /integrations/cloudflare/quickstart/ — pierwszy uruchamialny proces renderowania.
• /integrations/cloudflare/boot-and-discovery/ — szczegóły konfiguracji powiązań w kontenerze.
• /integrations/cloudflare/security-and-operations/ — ochrona przed fałszowaniem żądań po stronie serwera (server-side request forgery, SSRF), przypinanie certyfikatów oraz podręcznik operacyjny.
• /integrations/cloudflare/troubleshooting/ — tryby awarii odwzorowane na wyjątki.