Cloudflare-API-Referenz
Auf einen Blick
Abschnitt betitelt „Auf einen Blick“Das Paket NextPDF\Cloudflare ist eine Edge-Rendering-Brücke: Ihr PHP-Prozess stellt das HTML bereit, ein Cloudflare Worker führt den Headless-Browser aus. Das Paket stellt einen Worker-gestützten HTML-Renderer (CloudflareHtmlRenderer) samt den von ihm zurückgegebenen Wertobjekten bereit, außerdem eine Schutzschicht für Anfragen zum Absichern von Render-Endpunkten (ApiProtection), einen R2-Archivdienst zum Speichern gerenderter PDFs (R2ArchiveManager) und Helfer für gepinnten Transport zur TLS-/DNS-Härtung. Die Konfiguration liegt in drei unveränderlichen Objekten (CloudflareRendererConfig, ApiProtectionConfig, R2ArchiveConfig).
Beginnen Sie hier: Wenn Sie mit dem Paket noch nicht vertraut sind, erstellen Sie eine CloudflareRendererConfig, verdrahten Sie sie mit CloudflareHtmlRenderer und rufen Sie render() auf. Dieser eine Aufruf sendet Ihr HTML an den Worker und gibt ein CloudflareRenderResult mit den PDF-Bytes zurück. Alles andere (Schutz, Archivierung, Pinning) ist um diesen einen Aufruf herum angeordnet.
Häufige Aufgaben
Abschnitt betitelt „Häufige Aufgaben“Die folgenden Snippets zeigen die häufigsten Praxis-Workflows für dieses Paket. Jedes Snippet ist in sich abgeschlossen, anhand von src/Cloudflare/ gegen den Quellcode verifiziert und liest Geheimnisse aus der Umgebung.
Rendern Sie einen HTML-String an der Edge zu einem PDF — der kanonische Render-Aufruf:
<?php
declare(strict_types=1);
use GuzzleHttp\Client;use GuzzleHttp\Psr7\HttpFactory;use NextPDF\Cloudflare\CloudflareHtmlRenderer;use NextPDF\Cloudflare\CloudflareRendererConfig;
$httpFactory = new HttpFactory();
$renderer = new CloudflareHtmlRenderer( config: new CloudflareRendererConfig( workerUrl: 'https://pdf-renderer.example.workers.dev/render', apiToken: getenv('CF_PDF_TOKEN') ?: throw new RuntimeException('CF_PDF_TOKEN not set'), ), httpClient: new Client(), requestFactory: $httpFactory, streamFactory: $httpFactory, responseFactory: $httpFactory,);
$result = $renderer->render('<h1>Hello from the edge</h1>', widthPt: 595.28);
if ($result->isValid()) { file_put_contents('output.pdf', $result->pdfData);}Was es tut: Es sendet das HTML über HTTPS an den Worker und schreibt die zurückgegebenen A4-PDF-Bytes auf die Festplatte, sobald isValid() ein echtes PDF bestätigt.
Archivieren Sie ein gerendertes PDF in R2 und geben Sie einen kurzlebigen Link zurück:
<?php
declare(strict_types=1);
use NextPDF\Cloudflare\R2ArchiveConfig;use NextPDF\Cloudflare\R2ArchiveManager;
$archive = new R2ArchiveManager( config: R2ArchiveConfig::fromArray([ 'bucket_name' => 'pdf-archive', 'account_id' => getenv('CF_ACCOUNT_ID') ?: '', 'access_key_id' => getenv('R2_ACCESS_KEY_ID') ?: '', 'secret_access_key' => getenv('R2_SECRET_ACCESS_KEY') ?: '', ]), httpClient: $httpClient, // PSR-18 ClientInterface requestFactory: $requestFactory, // PSR-17 RequestFactoryInterface streamFactory: $streamFactory, // PSR-17 StreamFactoryInterface);
$upload = $archive->upload($result->pdfData, 'invoice-1234.pdf');
$signedUrl = $upload->isValid() ? $archive->generateSignedUrl($upload->key, expiresInSeconds: 600) : null;Was es tut: Es lädt die PDF-Bytes unter einem datumspartitionierten R2-Schlüssel hoch und erzeugt bei Erfolg eine vorsignierte URL, die 10 Minuten lang für den temporären Download gültig ist.
Sichern Sie einen Render-Endpunkt ab, bevor Sie teure Worker-Arbeit ausführen:
<?php
declare(strict_types=1);
use NextPDF\Cloudflare\ApiKeyValidator;use NextPDF\Cloudflare\ApiProtection;use NextPDF\Cloudflare\ApiProtectionConfig;
$protection = new ApiProtection( config: new ApiProtectionConfig(maxRequestsPerMinute: 30), keyValidator: new ApiKeyValidator([getenv('RENDER_API_KEY') ?: '']),);
$decision = $protection->checkRequest( clientId: $clientIp, payloadSize: strlen($html), apiKey: $presentedApiKey,);
if (!$decision->allowed) { // Reject with 429 and rate-limit headers before any render call. return [429, $decision->toHeaders(), $decision->denialReason];}Was es tut: Es validiert den API-Key, die Payload-Größe und anschließend das Rate-Limit pro Client und liefert eine einzelne Entscheidung samt Response-Headern, die bei einer abgelehnten Anfrage anzuhängen sind.
Renderer
Abschnitt betitelt „Renderer“Die Renderer-Tabelle ist die zentrale Oberfläche. Verwenden Sie sie, wenn Sie die Konfiguration zusammenstellen, den Renderer aufbauen oder die Render- und Erreichbarkeitsaufrufe absetzen.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Hinweise |
|---|---|---|---|---|---|
new CloudflareRendererConfig(string $workerUrl, string $apiToken, int $renderTimeout = 30, string $defaultCss = '', int $maxHtmlSize = 5000000, ?string $r2FontBucket = null, bool $fallbackToLocal = true, array $pinnedPublicKeys = [], array $backupPublicKeys = []) | Worker-URL, Bearer-Token, Timeout, CSS, Größenlimit, optionaler R2-Font-Bucket, Fallback-Flag, Pin-Sets. | Der lokale Fallback ist aktiviert; das Pinning ist deaktiviert, wenn die Pin-Arrays leer sind. | CloudflareRendererConfig | keine erwartet. | Halten Sie das API-Token geheim; bevorzugen Sie HTTPS-Worker-URLs. |
CloudflareRendererConfig::fromArray(array $config) | worker_url, api_token, render_timeout, default_css, max_html_size, r2_font_bucket, fallback_to_local, Pin-Arrays. | Fehlende optionale Schlüssel verwenden die Konstruktor-Standardwerte. | CloudflareRendererConfig | keine erwartet. | Passt zu Konfigurationsarrays im Framework-Stil. |
CloudflareRendererConfig::isValid() | keine. | Erfordert eine nicht-leere Worker-URL und ein nicht-leeres API-Token. | bool | keine erwartet. | Eine ungültige Konfiguration löst im Renderer den Fallback oder einen Fehler aus. |
CloudflareRendererConfig::allPublicKeyPins() | keine. | Kombiniert primäre und Backup-Public-Key-Pins. | list<string> | keine erwartet. | Eine leere Liste deaktiviert das Pinning. |
new CloudflareHtmlRenderer(CloudflareRendererConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?LocalRendererFactoryInterface $localRendererFactory = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null) | Konfiguration, PSR-HTTP-Abhängigkeiten, optionaler Logger, optionale lokale Fallback-Factory, optionale HTML-Policy, optionale Response-Factory. | Verwendet DefaultHtmlSecurityPolicy, wenn keine HTML-Policy übergeben wird. | CloudflareHtmlRenderer | Fehler bei der Container-Verdrahtung. | Die Response-Factory aktiviert bei Bedarf den gepinnten cURL-Transport. |
CloudflareHtmlRenderer::render(string $html, float $widthPt = 595.28, float $heightPt = 0, array $fontFiles = []) | HTML, Seitenbreite, Seitenhöhe, Font-Dateien in R2. | A4-Breite; automatische Höhe; keine Font-Dateien. | CloudflareRenderResult | CloudflareNotAvailableException, CloudflareRenderException, Validierungsfehler. | Validiert HTML-Größe und Worker-URL vor jeglicher Netzwerk-I/O. |
CloudflareHtmlRenderer::getHtmlSecurityPolicy() | keine. | Liefert die konfigurierte Policy der Parse-Schicht. | HtmlSecurityPolicyInterface | keine erwartet. | Setzen Sie sie zusammen mit dem Endpunkt-Schutz und der Worker-URL-Validierung ein. |
CloudflareHtmlRenderer::isAvailable() | keine. | HEAD-Anfrage an den Worker, wenn die Konfiguration gültig ist. | bool | Liefert bei Fehlern false. | Verwenden Sie sie für Bereitschaftsprüfungen, nicht als einzigen Laufzeitschutz. |
Renderer-Wertobjekte und Sicherheit
Abschnitt betitelt „Renderer-Wertobjekte und Sicherheit“Verwenden Sie diese Tabelle, wenn Sie die request/result-Wertobjekte (CloudflareRenderResult, CloudflareRenderPayload) benötigen oder die statischen Prüfungen der Transportschicht nutzen, die HTML, die Worker-URL und die DNS-Pins vor jeglicher Netzwerk-I/O validieren.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Hinweise |
|---|---|---|---|---|---|
new CloudflareRenderResult(string $pdfData, float $widthPt, float $heightPt, float $contentHeightPx = 0.0, string $renderLocation = '', float $renderTimeMs = 0.0) | PDF-Bytes, Breite, Höhe, gemessene Inhaltshöhe, Edge-Standort, Render-Zeit. | Leere Metadaten, wenn der Worker sie nicht meldet. | CloudflareRenderResult | keine erwartet. | Wird üblicherweise von CloudflareResponseParser::parse() zurückgegeben. |
CloudflareRenderResult::isValid() | keine. | Prüft auf nicht-leere PDF-Bytes, die mit einem PDF-Header beginnen. | bool | keine erwartet. | Verwenden Sie sie, bevor Sie archivieren oder Bytes an eine andere Schicht weitergeben. |
CloudflareRenderResult::size() | keine. | Zählt die gerenderten PDF-Bytes. | int | keine erwartet. | Speise dies in die Kontingent- und Audit-Logik ein. |
new CloudflareRenderPayload(string $html, float $widthPt, float $heightPt = 0, string $defaultCss = '', ?string $r2FontBucket = null, array $fontFiles = []) | HTML, Größe, CSS, optionaler R2-Font-Bucket, Font-Dateiliste. | Automatische Höhe, kein Standard-CSS, kein R2-Font-Bucket, keine Font-Dateien. | CloudflareRenderPayload | keine erwartet. | Wertobjekt für die Anfrage-Payload. |
CloudflareRenderPayload::toJson() | keine. | Serialisiert HTML, Größe, CSS und Font-Referenzen für den Worker. | string | Fehler bei der JSON-Kodierung. | Low-Level-API für die Anfrage-Payload. |
CloudflareResponseParser::parse(ResponseInterface $response, float $requestedWidthPt) | Worker-Antwort und angeforderte Breite. | Akzeptiert binäre PDF-Antworten und strukturierte JSON-Antworten. | CloudflareRenderResult | CloudflareRenderException bei fehlgeschlagener oder ungültiger Worker-Ausgabe. | Zentraler Parser, den der Renderer verwendet. |
CloudflareSecurityPolicy::validate(string $html, int $maxSize) | HTML-Eingabe und Größenlimit. | Wendet die HTML-Eingabe-Policy des Pakets an. | void | Validierungs-Exception. | Führen Sie Prüfungen für nicht vertrauenswürdige Eingaben außerhalb der Worker-Grenze durch. |
CloudflareSecurityPolicy::validateWorkerUrl(string $url) | Worker-URL. | Parst und validiert das Ziel. | array | Validierungs-Exception. | Blockiert unsichere Endpunkt-Formen vor jeglicher Netzwerk-I/O. |
CloudflareSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps) | Host und Liste der gepinnten IPs. | Verifiziert die DNS-Pin-Erwartungen. | void | Validierungs-Exception, wenn die Pins veraltet oder ungültig sind. | Verwenden Sie sie bei Betriebsprüfungen für gepinnte Deployments. |
API-Schutz
Abschnitt betitelt „API-Schutz“Verwenden Sie diese Tabelle, wenn Sie einen Render-Endpunkt absichern: API-Key-Validierung, Prüfungen von Payload-Größe und Rate-Limit sowie die result/header-Objekte, die daraus entstehen.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Hinweise |
|---|---|---|---|---|---|
new ApiProtection(ApiProtectionConfig $config, ?ApiKeyValidator $keyValidator = null, ?Closure $clock = null) | Schutzkonfiguration, optionaler Key-Validator, optionale Clock. | Verwendet die Systemzeit, wenn keine Clock übergeben wird. | ApiProtection | keine erwartet. | Übergeben Sie in Tests eine deterministische Clock. |
ApiProtection::checkRequest(string $clientId, int $payloadSize, string $apiKey = '') | Client-Kennung, Payload-Größe, optionaler API-Key. | Ein leerer API-Key ist nur zulässig, wenn die Konfiguration keine Keys verlangt. | ApiProtectionResult | keine erwartet. | Prüft API-Key, Größe und dann die Rate-Limits. |
ApiProtection::getRateLimit(string $clientId) | Client-Kennung. | Erfasst keine Anfrage. | RateLimitResult | keine erwartet. | Verwenden Sie sie, um Rate-Limit-Header hinzuzufügen. |
new ApiKeyValidator(array $validKeys = []) | Liste gültiger Klartext-Keys. | Eine leere Liste weist alle Keys zurück. | ApiKeyValidator | keine erwartet. | Speichern Sie Geheimnisse außerhalb des Codes und laden Sie sie über die Konfiguration. |
ApiKeyValidator::validate(string $key) | Roher Key. | Timing-sicherer Vergleich mit den konfigurierten Klartext-Keys. | bool | keine erwartet. | Sensibler Parameter; protokolliere keine rohen Keys. |
ApiKeyValidator::addKey(string $key) | Roher Key. | Fügt einer neuen Validator-Instanz einen gehashten Key hinzu. | self | keine erwartet. | Behandeln Sie die zurückgegebene Instanz als den aktualisierten Validator. |
ApiKeyValidator::revokeKey(string $key) | Roher Key. | Entfernt den passenden Hash aus einer neuen Validator-Instanz. | self | keine erwartet. | Behandeln Sie die zurückgegebene Instanz als den aktualisierten Validator. |
ApiKeyValidator::hashKey(string $key) | Roher Key. | Erzeugt die gespeicherte Hash-Darstellung. | string | keine erwartet. | Geben Sie Hashes nicht in Logs oder Client-Antworten preis. |
ApiKeyValidator::validateHashed(string $key, array $hashedKeys) | Roher Key und Kandidaten-Hashes. | Vergleich in konstanter Zeit mit den übergebenen Hashes. | bool | keine erwartet. | Low-Level-Helfer für eigene Key-Stores. |
new ApiProtectionConfig(int $maxRequestsPerMinute = 60, int $maxRequestsPerHour = 1000, int $maxPayloadSizeBytes = 10485760, array $allowedOrigins = [], bool $requireApiKey = true, string $apiKeyHeader = 'X-Api-Key', int $rateLimitWindowSeconds = 60) | Anfragelimits, Payload-Limit, erlaubte Origins, API-Key-Pflicht, Header-Name, Fensterlänge. | 60/minute, 1000/hour, 10 MiB Payload, API-Key erforderlich. | ApiProtectionConfig | keine erwartet. | Erzeugen Sie sie direkt in Tests oder laden Sie sie mit fromArray(). |
ApiProtectionConfig::fromArray(array $data) | max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header, rate_limit_window_seconds. | Fehlende Schlüssel verwenden die Konstruktor-Standardwerte. | ApiProtectionConfig | keine erwartet. | Verwenden Sie sie zum Laden der Framework-Konfiguration. |
ApiProtectionConfig::isValid() | keine. | Erfordert positive Limits und kohärente size/window-Werte. | bool | keine erwartet. | Validieren Sie, bevor Sie einen Endpunkt freigeben. |
new ApiProtectionResult(bool $allowed, string $denialReason = '', ?RateLimitResult $rateLimit = null) | Entscheidung, Ablehnungsgrund, optionales Rate-Limit-Ergebnis. | Leerer Ablehnungsgrund und kein Rate-Limit-Ergebnis. | ApiProtectionResult | keine erwartet. | Wird von ApiProtection::checkRequest() zurückgegeben. |
ApiProtectionResult::toHeaders() | keine. | Gibt Rate-Limit-Header aus, wenn Rate-Daten vorhanden sind. | array<string, string> | keine erwartet. | Fügen Sie sie Worker- oder Framework-Antworten hinzu. |
new RateLimitResult(bool $allowed, int $remainingRequests, int $retryAfterSeconds, string $clientId) | Entscheidung, verbleibende Anzahl, Wiederholungsverzögerung, Client-ID. | Keine Standardwerte. | RateLimitResult | keine erwartet. | Unveränderliches Ergebnis einer einzelnen Prüfung. |
RateLimitResult::toHeaders() | keine. | Gibt Header für das verbleibende Limit und den Reset aus. | array<string, string> | keine erwartet. | Verwenden Sie sie für Observability und das Client-Backoff. |
new RateLimitEntry(string $clientId, int $requestCount = 0, int $windowStart = 0, int $hourlyCount = 0, int $hourlyWindowStart = 0) | Client-ID und veränderbare Zähler. | Die Zähler beginnen bei null. | RateLimitEntry | keine erwartet. | In-Memory-Tracking-Objekt. |
RateLimitEntry::increment() | keine. | Erhöht den In-Memory-Zähler für eine Client-/Window-Kombination. | void | keine erwartet. | Low-Level-Helfer, den ApiProtection verwendet. |
RateLimitEntry::isExpired(int $windowSeconds) | Fensterlänge in Sekunden. | Vergleicht mit der aktuellen Zeit. | bool | keine erwartet. | Laufzeit-Helfer für den Ablauf. |
RateLimitEntry::isExpiredAt(int $now, int $windowSeconds) | Clock-Wert und Fensterlänge. | Vergleicht mit dem übergebenen Clock-Wert. | bool | keine erwartet. | Deterministischer Test-Helfer. |
RateLimitEntry::reset() | keine. | Setzt Zähler und Fenster-Startzeit zurück. | void | keine erwartet. | Wird verwendet, wenn ein neues Fenster beginnt. |
R2-Archiv
Abschnitt betitelt „R2-Archiv“Verwenden Sie diese Tabelle, wenn Sie gerenderte PDFs in Cloudflare R2 speichern: den Archiv-Service, seine Konfigurations- und Objektschlüsseltypen sowie das Upload-Ergebnis, das Sie prüfen, bevor Sie eine URL freigeben.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Hinweise |
|---|---|---|---|---|---|
new R2ArchiveManager(R2ArchiveConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory) | R2-Konfiguration, PSR-HTTP-Factories und -Client. | Kein Netzwerkaufruf während der Konstruktion. | R2ArchiveManager | Fehler bei der Container-Verdrahtung. | Zentraler Archiv-Service. |
R2ArchiveManager::upload(string $pdfData, string $filename, array $metadata = []) | Rohe PDF-Bytes, ursprünglicher Dateiname, String-Metadaten. | Leere Metadaten; datumspartitionierter Schlüssel. | R2UploadResult | Liefert bei Konfigurations-, Größen-, HTTP- oder Transportfehlern ein erfolgloses Ergebnis. | Wirft bei einem normalen Upload-Fehler keine Exception. |
R2ArchiveManager::generateSignedUrl(string $key, int $expiresInSeconds = 3600) | Objektschlüssel und URL-TTL. | Signierte URL mit einer Stunde Gültigkeit. | string | Signierungsfehler durch ungültige Konfiguration. | Halten Sie die TTLs für sensible PDFs kurz. |
R2ArchiveManager::buildObjectKey(string $filename) | Ursprünglicher Dateiname. | Verwendet den konfigurierten Pfadpräfix und das aktuelle Datum. | R2ObjectKey | keine erwartet. | Verwenden Sie sie für eine vorhersehbare Archivpartitionierung. |
R2ArchiveManager::createPutRequest(R2ObjectKey $key, string $data, array $metadata = []) | Objektschlüssel, rohe Bytes, Metadaten. | Signiert eine PUT-Anfrage. | RequestInterface | Fehler bei der Anfrage-Konstruktion. | Low-Level-API für eigene Transporte. |
new R2ArchiveConfig(string $bucketName, string $accountId, string $accessKeyId, string $secretAccessKey, string $endpoint = '', string $pathPrefix = 'pdfs/', int $maxFileSizeBytes = 104857600) | Bucket, Account-ID, Zugangsdaten, Endpunkt-Override, Schlüsselpräfix, maximale Objektgröße. | Abgeleiteter Endpunkt, Präfix pdfs/, 100 MiB maximale Objektgröße. | R2ArchiveConfig | InvalidArgumentException bei ungültigen Bucket-Namen. | Behandeln Sie Zugangsdaten als geheime Konfigurationswerte. |
R2ArchiveConfig::fromArray(array $data) | Account-ID, Bucket, Zugangsdaten, Pfadpräfix, Endpunkt-Override, maximale Größe. | Fehlende Werte verwenden die Konstruktor-Standardwerte. | R2ArchiveConfig | Ungültiger Bucket-Name, sofern angegeben. | Verwenden Sie sie zum Laden der Anwendungskonfiguration. |
R2ArchiveConfig::isValid() | keine. | Erfordert nicht-leere Werte für Account, Bucket, Access-Key und Secret-Key. | bool | keine erwartet. | Eine ungültige Konfiguration lässt Uploads mit strukturierten Ergebnissen fehlschlagen. |
R2ArchiveConfig::getEndpoint() | keine. | Verwendet den expliziten Endpunkt oder leitet den Cloudflare-R2-Endpunkt aus der Account-ID ab. | string | keine erwartet. | Wird für die Konstruktion signierter Anfragen verwendet. |
new R2ObjectKey(string $key, string $bucket) | Vollständiger Objektschlüssel und Bucket. | Keine Normalisierung. | R2ObjectKey | keine erwartet. | Wird üblicherweise von R2ObjectKey::generate() erstellt. |
R2ObjectKey::generate(string $prefix, string $filename, ?DateTimeInterface $date = null) | Präfix, ursprünglicher Dateiname, optionales Datum. | Datumspartitionierter, bereinigter Objektschlüssel. | R2ObjectKey | keine erwartet. | Übergeben Sie in Tests ein Datum für deterministische Schlüssel. |
R2ObjectKey::fullPath() | keine. | Verbindet den Partitionspfad und den Objektdateinamen. | string | keine erwartet. | Speichern Sie diesen Wert als Objektschlüssel. |
new R2UploadResult(bool $success, string $key, string $etag = '', int $size = 0, string $error = '') | Erfolgs-Flag, Objektschlüssel, ETag, Byte-Größe, Fehlermeldung. | Leeres ETag, Größe null, leerer Fehler. | R2UploadResult | keine erwartet. | Wird von R2ArchiveManager::upload() zurückgegeben. |
R2UploadResult::isValid() | keine. | Gültig, wenn der Upload erfolgreich war und sowohl Schlüssel als auch ETag vorhanden sind. | bool | keine erwartet. | Prüfen Sie, bevor Sie URLs freigeben. |
R2UploadResult::publicUrl(string $customDomain = '') | Optionale benutzerdefinierte öffentliche Domain. | Liefert den reinen Objektschlüssel, wenn keine benutzerdefinierte Domain übergeben wird. | string | keine erwartet. | Vermeiden Sie öffentliche URLs für sensible Dokumente, sofern die Policy es nicht zulässt. |
Transport-Helfer
Abschnitt betitelt „Transport-Helfer“Verwenden Sie diese Tabelle nur für Low-Level-Verdrahtung: IP-/SPKI-Pinning auf cURL-Ebene und die Local-Renderer-Verträge, die als Fallback-Pfad dienen, wenn der Worker nicht erreichbar ist.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Hinweise |
|---|---|---|---|---|---|
new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30) | PSR-17-Factories, gepinnte IPs, gepinnte Public Keys, Timeout. | Keine Pins und 30 Sekunden Timeout. | PinnedCurlTransport | keine erwartet. | Verwenden Sie sie nur, wenn Pinning auf cURL-Ebene erforderlich ist. |
PinnedCurlTransport::sendRequest(RequestInterface $request) | PSR-7-Anfrage. | Sendet über cURL mit konfiguriertem Timeout und Pinning-Kontrollen. | ResponseInterface | PSR-18-Transport-Exceptions. | Verwenden Sie sie nur, wenn die HTTP-Clients des Frameworks dieselbe Pinning-Policy nicht durchsetzen können. |
PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port) | Anfrage, Ziel-Host, Ziel-Port. | Baut das cURL-Options-Array, das sendRequest() verwendet. | array | Fehler durch ungültige Anfrage oder Pin-Konfiguration. | Low-Level-Hook für Tests und Diagnose. |
LocalRendererInterface::render(string $html, array $options = []) | HTML und Renderer-Optionen. | Nur ein Vertrag; die Implementierung legt die Standardwerte fest. | string | Implementierungsspezifische Render-Fehler. | Wird als lokaler Fallback verwendet, wenn das Worker-Rendering nicht verfügbar ist. |
LocalRendererFactoryInterface::create() | keine. | Erstellt eine Local-Renderer-Implementierung. | LocalRendererInterface | Factory- oder Abhängigkeitsfehler. | Hält die Konstruktion des Fallback-Renderers aus CloudflareHtmlRenderer heraus. |
Entwicklungshinweise
Abschnitt betitelt „Entwicklungshinweise“- Behandeln Sie die Worker-URL als Netzwerkgrenze. Validieren Sie Ziel, Größe und Authentifizierung vor dem Rendern.
- Verwenden Sie die Ergebnisse des API-Schutzes als Policy-Ausgaben, nicht als Exception-Steuerfluss.
- R2-Uploads liefern strukturierte Erfolgs- oder Fehlerergebnisse; behandeln Sie beide Pfade.