Dokumentacja API Cloudflare

W skrócie

Pakiet NextPDF\Cloudflare zapewnia warstwę pośrednią do renderowania na brzegu sieci. Proces PHP przechowuje kod HTML (Hypertext Markup Language), a Cloudflare Worker steruje bezgłową przeglądarką. Pakiet udostępnia renderer HTML oparty na Workerze (CloudflareHtmlRenderer) oraz zwracane przez niego obiekty wartości, warstwę ochrony żądań dla punktów końcowych renderowania (ApiProtection), usługę archiwizacji R2 dla wyrenderowanych plików PDF (Portable Document Format) (R2ArchiveManager) oraz funkcje pomocnicze przypiętego transportu do wzmacniania zabezpieczeń TLS (Transport Layer Security) i DNS (Domain Name System). Konfigurację zawarto w trzech niezmiennych obiektach (CloudflareRendererConfig, ApiProtectionConfig, R2ArchiveConfig).

Na początek zbuduj obiekt CloudflareRendererConfig, podłącz go do CloudflareHtmlRenderer i wywołaj render(). To wywołanie wysyła kod HTML do Workera i zwraca CloudflareRenderResult z bajtami PDF. Ochrona, archiwizacja i przypinanie działają jako warstwy wokół tego wywołania.

Typowe zadania

Poniższe fragmenty obejmują przepływy pracy, których prawdopodobnie użyjesz najczęściej. Każdy z nich jest samowystarczalny, zweryfikowany względem src/Cloudflare/ i odczytuje sekrety ze środowiska.

Wyrenderuj ciąg HTML do pliku PDF na brzegu sieci za pomocą kanonicznego wywołania:

<?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);
}

Co robi: wysyła kod HTML do Workera za pośrednictwem protokołu HTTPS (Hypertext Transfer Protocol Secure) i po potwierdzeniu przez isValid(), że wynik jest prawdziwym plikiem PDF, zapisuje zwrócone bajty PDF w formacie A4 na dysku.

Zarchiwizuj wyrenderowany plik PDF w R2 i zwróć krótkotrwały odnośnik:

<?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;

Co robi: przesyła bajty PDF pod klucz R2 partycjonowany według daty i po powodzeniu tworzy 10-minutowy, wstępnie podpisany adres URL (uniform resource locator) do tymczasowego pobrania.

Zabezpiecz punkt końcowy renderowania, zanim uruchomi kosztowną pracę Workera:

<?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];
}

Co robi: weryfikuje klucz API i rozmiar ładunku, sprawdza limit żądań na klienta oraz zwraca jedną decyzję wraz z nagłówkami odpowiedzi do dołączenia, gdy żądanie jest odrzucane.

renderer

Ta tabela opisuje podstawową powierzchnię renderera. Używaj jej przy tworzeniu konfiguracji, budowaniu renderera albo wykonywaniu wywołań renderowania i sprawdzaniu dostępności.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
`new CloudflareRendererConfig(string $workerUrl, string $apiToken, int $renderTimeout = 30, string $defaultCss = '', int $maxHtmlSize = 5000000, ?string $r2FontBucket = null, bool $fallbackToLocal = true, array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	Adres URL Workera, token bearer, limit czasu, arkusze stylów CSS (Cascading Style Sheets), limit rozmiaru, opcjonalny zasobnik czcionek R2, flaga awaryjna, zestawy przypięć.	Lokalne rozwiązanie awaryjne jest włączone; przypinanie jest wyłączone, gdy tablice przypięć są puste.	`CloudflareRendererConfig`	Brak oczekiwanych.	Trzymaj token API w tajemnicy; preferuj adresy URL Workera używające protokołu HTTPS.
`CloudflareRendererConfig::fromArray(array $config)`	`worker_url`, `api_token`, `render_timeout`, `default_css`, `max_html_size`, `r2_font_bucket`, `fallback_to_local`, tablice przypięć.	Brakujące klucze opcjonalne przyjmują wartości domyślne konstruktora.	`CloudflareRendererConfig`	Brak oczekiwanych.	Stosuj w przypadku tablic konfiguracyjnych w stylu frameworka.
`CloudflareRendererConfig::isValid()`	brak.	Wymaga niepustego adresu URL Workera i tokenu API.	`bool`	Brak oczekiwanych.	Nieprawidłowa konfiguracja uruchamia w rendererze ścieżkę awaryjną albo powoduje niepowodzenie.
`CloudflareRendererConfig::allPublicKeyPins()`	brak.	Łączy podstawowe i zapasowe przypięcia kluczy publicznych.	`list<string>`	Brak oczekiwanych.	Pusta lista wyłącza przypinanie.
`new CloudflareHtmlRenderer(CloudflareRendererConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?LocalRendererFactoryInterface $localRendererFactory = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Konfiguracja, zależności HTTP (Hypertext Transfer Protocol) zgodne z rekomendacjami PSR (PHP Standards Recommendation), opcjonalny rejestrator, opcjonalna fabryka lokalnego rozwiązania awaryjnego, opcjonalna polityka HTML, opcjonalna fabryka odpowiedzi.	Używa `DefaultHtmlSecurityPolicy`, gdy nie podano polityki HTML.	`CloudflareHtmlRenderer`	Błędy okablowania kontenera.	Fabryka odpowiedzi włącza w razie potrzeby przypięty transport cURL.
`CloudflareHtmlRenderer::render(string $html, float $widthPt = 595.28, float $heightPt = 0, array $fontFiles = [])`	HTML, szerokość strony, wysokość strony, pliki czcionek w R2.	Szerokość A4, automatyczna wysokość, brak plików czcionek.	`CloudflareRenderResult`	`CloudflareNotAvailableException`, `CloudflareRenderException`, niepowodzenia weryfikacji.	Weryfikuje rozmiar HTML i adres URL Workera przed sieciowymi operacjami wejścia/wyjścia (we/wy).
`CloudflareHtmlRenderer::getHtmlSecurityPolicy()`	brak.	Zwraca skonfigurowaną politykę dla warstwy analizy.	`HtmlSecurityPolicyInterface`	Brak oczekiwanych.	Stosuj wraz z ochroną punktu końcowego i weryfikacją adresu URL Workera.
`CloudflareHtmlRenderer::isAvailable()`	brak.	Wysyła żądanie HEAD do Workera, gdy konfiguracja jest prawidłowa.	`bool`	Zwraca `false` przy błędach.	Używaj do kontroli gotowości, a nie jako jedynego zabezpieczenia w czasie działania.

Obiekty wartości renderera i bezpieczeństwo

Używaj tej tabeli dla obiektów wartości żądań i wyników (CloudflareRenderResult, CloudflareRenderPayload) oraz statycznych kontroli warstwy transportu, które weryfikują HTML, adres URL Workera i przypięcia DNS przed sieciowymi operacjami we/wy.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
`new CloudflareRenderResult(string $pdfData, float $widthPt, float $heightPt, float $contentHeightPx = 0.0, string $renderLocation = '', float $renderTimeMs = 0.0)`	Bajty PDF, szerokość, wysokość, zmierzona wysokość treści, lokalizacja brzegowa, czas renderowania.	Metadane są puste, gdy Worker ich nie zgłasza.	`CloudflareRenderResult`	Brak oczekiwanych.	Zwykle zwracany przez `CloudflareResponseParser::parse()`.
`CloudflareRenderResult::isValid()`	brak.	Sprawdza, czy bajty PDF są niepuste i czy zaczynają się od nagłówka PDF.	`bool`	Brak oczekiwanych.	Stosuj przed archiwizacją lub przekazaniem bajtów do innej warstwy.
`CloudflareRenderResult::size()`	brak.	Liczy wyrenderowane bajty PDF.	`int`	Brak oczekiwanych.	Wykorzystuj w logice limitów i audytu.
`new CloudflareRenderPayload(string $html, float $widthPt, float $heightPt = 0, string $defaultCss = '', ?string $r2FontBucket = null, array $fontFiles = [])`	HTML, rozmiar, CSS, opcjonalny zasobnik czcionek R2, lista plików czcionek.	Automatyczna wysokość, brak domyślnego CSS, brak zasobnika czcionek R2, brak plików czcionek.	`CloudflareRenderPayload`	Brak oczekiwanych.	Obiekt wartości ładunku żądania.
`CloudflareRenderPayload::toJson()`	brak.	Serializuje HTML, rozmiar, CSS oraz odwołania do czcionek do JSON (JavaScript Object Notation) dla Workera.	`string`	Błędy kodowania JSON.	Niskopoziomowe API ładunku żądania.
`CloudflareResponseParser::parse(ResponseInterface $response, float $requestedWidthPt)`	Odpowiedź Workera i żądana szerokość.	Obsługuje binarne odpowiedzi PDF oraz ustrukturyzowane odpowiedzi JSON.	`CloudflareRenderResult`	`CloudflareRenderException` przy nieudanym lub nieprawidłowym wyniku Workera.	Centralny parser używany przez renderer.
`CloudflareSecurityPolicy::validate(string $html, int $maxSize)`	Dane wejściowe HTML i limit rozmiaru.	Stosuje politykę pakietu dotyczącą danych wejściowych HTML.	`void`	Wyjątek weryfikacji.	Utrzymuj kontrole niezaufanych danych wejściowych poza granicą Workera.
`CloudflareSecurityPolicy::validateWorkerUrl(string $url)`	Adres URL Workera.	Analizuje i weryfikuje miejsce docelowe.	`array`	Wyjątek weryfikacji.	Blokuje niebezpieczne postacie punktów końcowych przed operacjami sieciowymi we/wy.
`CloudflareSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Host i lista przypiętych adresów IP.	Weryfikuje oczekiwane przypięcia DNS.	`void`	Wyjątek weryfikacji, gdy przypięcia są nieaktualne lub nieprawidłowe.	Stosuj podczas kontroli operacyjnych dla wdrożeń z przypięciami.

Ochrona API

Używaj tej tabeli, gdy zabezpieczasz punkt końcowy renderowania: weryfikacja klucza API, kontrole rozmiaru ładunku i limitu żądań oraz obiekty wyniku i nagłówków, które te kontrole tworzą.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
`new ApiProtection(ApiProtectionConfig $config, ?ApiKeyValidator $keyValidator = null, ?Closure $clock = null)`	Konfiguracja ochrony, opcjonalny walidator kluczy, opcjonalny zegar.	Używa czasu systemowego, gdy nie podano zegara.	`ApiProtection`	Brak oczekiwanych.	W testach wstrzykuj deterministyczny zegar.
`ApiProtection::checkRequest(string $clientId, int $payloadSize, string $apiKey = '')`	Identyfikator klienta, rozmiar ładunku, opcjonalny klucz API.	Pusty klucz API jest dozwolony tylko wtedy, gdy konfiguracja nie wymaga kluczy.	`ApiProtectionResult`	Brak oczekiwanych.	Sprawdza klucz API i rozmiar, a następnie stosuje limit żądań.
`ApiProtection::getRateLimit(string $clientId)`	Identyfikator klienta.	Nie rejestruje żądania.	`RateLimitResult`	Brak oczekiwanych.	Stosuj do dodawania nagłówków limitu żądań.
`new ApiKeyValidator(array $validKeys = [])`	Lista prawidłowych kluczy w tekście jawnym.	Pusta lista odrzuca wszystkie klucze.	`ApiKeyValidator`	Brak oczekiwanych.	Sekrety przechowuj poza kodem i wczytuj je z konfiguracji.
`ApiKeyValidator::validate(string $key)`	Surowy klucz.	Porównuje ze skonfigurowanymi kluczami w tekście jawnym, stosując logikę odporną na ataki czasowe.	`bool`	Brak oczekiwanych.	Parametr jest wrażliwy; nie zapisuj surowych kluczy w dziennikach.
`ApiKeyValidator::addKey(string $key)`	Surowy klucz.	Dodaje hasz klucza do nowej instancji walidatora.	`self`	Brak oczekiwanych.	Traktuj zwróconą instancję jako zaktualizowany walidator.
`ApiKeyValidator::revokeKey(string $key)`	Surowy klucz.	Zwraca nową instancję walidatora bez pasującego hasza.	`self`	Brak oczekiwanych.	Traktuj zwróconą instancję jako zaktualizowany walidator.
`ApiKeyValidator::hashKey(string $key)`	Surowy klucz.	Tworzy reprezentację hasza przeznaczoną do przechowywania.	`string`	Brak oczekiwanych.	Nie ujawniaj haszy w dziennikach ani w odpowiedziach dla klienta.
`ApiKeyValidator::validateHashed(string $key, array $hashedKeys)`	Surowy klucz i kandydujące hasze.	Porównuje z dostarczonymi haszami w czasie stałym.	`bool`	Brak oczekiwanych.	Niskopoziomowa funkcja pomocnicza do niestandardowych magazynów kluczy.
`new ApiProtectionConfig(int $maxRequestsPerMinute = 60, int $maxRequestsPerHour = 1000, int $maxPayloadSizeBytes = 10485760, array $allowedOrigins = [], bool $requireApiKey = true, string $apiKeyHeader = 'X-Api-Key', int $rateLimitWindowSeconds = 60)`	Limity żądań, limit ładunku, dozwolone źródła, wymóg klucza API, nazwa nagłówka, długość okna.	60/minute, 1000/hour, ładunek 10 MiB, wymagany klucz API.	`ApiProtectionConfig`	Brak oczekiwanych.	Twórz bezpośrednio w testach lub wczytuj za pomocą `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`.	Brakujące klucze przyjmują wartości domyślne konstruktora.	`ApiProtectionConfig`	Brak oczekiwanych.	Stosuj do wczytywania konfiguracji frameworka.
`ApiProtectionConfig::isValid()`	brak.	Wymaga dodatnich limitów oraz spójnych wartości rozmiaru i okna.	`bool`	Brak oczekiwanych.	Sprawdź przed udostępnieniem punktu końcowego.
`new ApiProtectionResult(bool $allowed, string $denialReason = '', ?RateLimitResult $rateLimit = null)`	Decyzja, powód odmowy, opcjonalny wynik limitu żądań.	Pusty powód odmowy i brak wyniku limitu żądań.	`ApiProtectionResult`	Brak oczekiwanych.	Zwracany przez `ApiProtection::checkRequest()`.
`ApiProtectionResult::toHeaders()`	brak.	Emituje nagłówki limitu żądań, gdy dostępne są dane o limicie.	`array<string, string>`	Brak oczekiwanych.	Dołączaj do odpowiedzi Workera lub frameworka.
`new RateLimitResult(bool $allowed, int $remainingRequests, int $retryAfterSeconds, string $clientId)`	Decyzja, liczba pozostałych żądań, opóźnienie przed ponowieniem, identyfikator klienta (ID).	Brak wartości domyślnych.	`RateLimitResult`	Brak oczekiwanych.	Niezmienny wynik jednej kontroli.
`RateLimitResult::toHeaders()`	brak.	Emituje nagłówki z pozostałym limitem i czasem resetu.	`array<string, string>`	Brak oczekiwanych.	Stosuj do obserwowalności i opóźniania ponowień po stronie klienta.
`new RateLimitEntry(string $clientId, int $requestCount = 0, int $windowStart = 0, int $hourlyCount = 0, int $hourlyWindowStart = 0)`	Identyfikator klienta i modyfikowalne liczniki.	Liczniki zaczynają się od zera.	`RateLimitEntry`	Brak oczekiwanych.	Obiekt śledzący w pamięci.
`RateLimitEntry::increment()`	brak.	Zwiększa licznik w pamięci dla jednej pary klient/okno.	`void`	Brak oczekiwanych.	Niskopoziomowa funkcja pomocnicza używana przez `ApiProtection`.
`RateLimitEntry::isExpired(int $windowSeconds)`	Długość okna w sekundach.	Porównuje z bieżącym czasem.	`bool`	Brak oczekiwanych.	Funkcja pomocnicza do sprawdzania wygaśnięcia w czasie działania.
`RateLimitEntry::isExpiredAt(int $now, int $windowSeconds)`	Wartość zegara i długość okna.	Porównuje z dostarczoną wartością zegara.	`bool`	Brak oczekiwanych.	Deterministyczna funkcja pomocnicza do testów.
`RateLimitEntry::reset()`	brak.	Zeruje licznik i czas rozpoczęcia okna.	`void`	Brak oczekiwanych.	Używane przy rozpoczęciu nowego okna.

Archiwum R2

Używaj tej tabeli, gdy przechowujesz wyrenderowane pliki PDF w Cloudflare R2: usługa archiwum, jej konfiguracja, typy kluczy obiektów oraz wynik przesłania, który trzeba sprawdzić, zanim udostępnisz adres URL.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
`new R2ArchiveManager(R2ArchiveConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory)`	Konfiguracja R2 oraz zgodne z PSR fabryki i klient HTTP.	Brak wywołania sieciowego podczas tworzenia.	`R2ArchiveManager`	Błędy okablowania kontenera.	Główna usługa archiwum.
`R2ArchiveManager::upload(string $pdfData, string $filename, array $metadata = [])`	Surowe bajty PDF, oryginalna nazwa pliku, metadane tekstowe.	Puste metadane; klucz partycjonowany według daty.	`R2UploadResult`	Zwraca wynik niepowodzenia przy błędzie konfiguracji, rozmiaru, HTTP lub transportu.	Nie zgłasza wyjątku dla zwykłego niepowodzenia przesłania.
`R2ArchiveManager::generateSignedUrl(string $key, int $expiresInSeconds = 3600)`	Klucz obiektu i czas życia adresu URL (TTL).	Godzinny podpisany adres URL.	`string`	Błędy podpisywania wynikające z nieprawidłowej konfiguracji.	Stosuj krótkie wartości TTL dla wrażliwych plików PDF.
`R2ArchiveManager::buildObjectKey(string $filename)`	Oryginalna nazwa pliku.	Używa skonfigurowanego prefiksu ścieżki i bieżącej daty.	`R2ObjectKey`	Brak oczekiwanych.	Stosuj do przewidywalnego partycjonowania archiwum.
`R2ArchiveManager::createPutRequest(R2ObjectKey $key, string $data, array $metadata = [])`	Klucz obiektu, surowe bajty, metadane.	Podpisuje żądanie PUT.	`RequestInterface`	Błędy tworzenia żądania.	Niskopoziomowe API do niestandardowych transportów.
`new R2ArchiveConfig(string $bucketName, string $accountId, string $accessKeyId, string $secretAccessKey, string $endpoint = '', string $pathPrefix = 'pdfs/', int $maxFileSizeBytes = 104857600)`	Zasobnik, identyfikator konta, poświadczenia, nadpisanie punktu końcowego, prefiks klucza, maksymalny rozmiar obiektu.	Wyprowadzony punkt końcowy, prefiks `pdfs/`, maksymalny rozmiar obiektu 100 MiB.	`R2ArchiveConfig`	`InvalidArgumentException` przy nieprawidłowych nazwach zasobników.	Traktuj poświadczenia jako sekretną konfigurację.
`R2ArchiveConfig::fromArray(array $data)`	Identyfikator konta, zasobnik, poświadczenia, prefiks ścieżki, nadpisanie punktu końcowego, maksymalny rozmiar.	Brakujące wartości przyjmują wartości domyślne konstruktora.	`R2ArchiveConfig`	Nieprawidłowa nazwa zasobnika, jeśli została podana.	Stosuj do wczytywania konfiguracji aplikacji.
`R2ArchiveConfig::isValid()`	brak.	Wymaga niepustego konta, zasobnika, klucza dostępu i klucza tajnego.	`bool`	Brak oczekiwanych.	Nieprawidłowa konfiguracja sprawia, że przesłania kończą się niepowodzeniem i zwracają ustrukturyzowane wyniki.
`R2ArchiveConfig::getEndpoint()`	brak.	Używa jawnie podanego punktu końcowego albo wyprowadza punkt końcowy Cloudflare R2 z identyfikatora konta.	`string`	Brak oczekiwanych.	Używane do tworzenia podpisanego żądania.
`new R2ObjectKey(string $key, string $bucket)`	Pełny klucz obiektu i zasobnik.	Brak normalizacji.	`R2ObjectKey`	Brak oczekiwanych.	Zwykle tworzony przez `R2ObjectKey::generate()`.
`R2ObjectKey::generate(string $prefix, string $filename, ?DateTimeInterface $date = null)`	Prefiks, oryginalna nazwa pliku, opcjonalna data.	Oczyszczony klucz obiektu partycjonowany według daty.	`R2ObjectKey`	Brak oczekiwanych.	W testach wstrzykuj datę, aby uzyskać deterministyczne klucze.
`R2ObjectKey::fullPath()`	brak.	Łączy ścieżkę partycji i nazwę pliku obiektu.	`string`	Brak oczekiwanych.	Przechowuj tę wartość jako klucz obiektu.
`new R2UploadResult(bool $success, string $key, string $etag = '', int $size = 0, string $error = '')`	Flaga powodzenia, klucz obiektu, znacznik encji (ETag), rozmiar w bajtach, komunikat o błędzie.	Pusty ETag, zerowy rozmiar, pusty komunikat o błędzie.	`R2UploadResult`	Brak oczekiwanych.	Zwracany przez `R2ArchiveManager::upload()`.
`R2UploadResult::isValid()`	brak.	Prawidłowy, gdy przesłanie się powiodło i obecne są zarówno klucz, jak i ETag.	`bool`	Brak oczekiwanych.	Sprawdź przed udostępnieniem adresów URL.
`R2UploadResult::publicUrl(string $customDomain = '')`	Opcjonalna niestandardowa domena publiczna.	Zwraca sam klucz obiektu, gdy nie podano niestandardowej domeny.	`string`	Brak oczekiwanych.	Unikaj publicznych adresów URL dla wrażliwych dokumentów, chyba że polityka na to pozwala.

Funkcje pomocnicze transportu

Używaj tej tabeli wyłącznie przy niskopoziomowym okablowaniu: przypinanie adresów IP (Internet Protocol) i SubjectPublicKeyInfo (SPKI) na poziomie cURL oraz kontrakty lokalnego renderera używane jako ścieżka awaryjna, gdy Worker jest nieosiągalny.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	Fabryki PSR-17, przypięte adresy IP, przypięte klucze publiczne, limit czasu.	Brak przypięć i 30-sekundowy limit czasu.	`PinnedCurlTransport`	Brak oczekiwanych.	Stosuj tylko wtedy, gdy wymagane jest przypinanie na poziomie cURL.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	Żądanie PSR-7.	Wysyła przez cURL ze skonfigurowanym limitem czasu i kontrolami przypinania.	`ResponseInterface`	Wyjątki transportu PSR-18.	Stosuj tylko wtedy, gdy klienci HTTP frameworka nie mogą wymusić tej samej polityki przypinania.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Żądanie, host docelowy, port docelowy.	Buduje tablicę opcji cURL używaną przez `sendRequest()`.	`array`	Błędy nieprawidłowego żądania lub konfiguracji przypięć.	Niskopoziomowy punkt zaczepienia do testów i diagnostyki.
`LocalRendererInterface::render(string $html, array $options = [])`	HTML i opcje renderera.	Tylko kontrakt; wartości domyślne ustala implementacja.	`string`	Błędy renderowania zależne od implementacji.	Używane jako lokalne rozwiązanie awaryjne, gdy renderowanie przez Workera jest niedostępne.
`LocalRendererFactoryInterface::create()`	brak.	Tworzy implementację lokalnego renderera.	`LocalRendererInterface`	Błędy fabryki lub zależności.	Utrzymuje tworzenie awaryjnego renderera poza `CloudflareHtmlRenderer`.

Uwagi dotyczące programowania

Traktuj adres URL Workera jako granicę sieci. Sprawdź miejsce docelowe, rozmiar i uwierzytelnienie przed renderowaniem.
Wyniki ochrony API traktuj jako rezultaty polityki, a nie jako mechanizm sterowania przepływem przez wyjątki.
Przesłania do R2 zwracają ustrukturyzowane wyniki powodzenia lub błędu; obsłuż obie ścieżki.