Tham khảo API Cloudflare
Tổng quan
Phần tiêu đề “Tổng quan”Gói NextPDF\Cloudflare làm cầu nối cho việc kết xuất ở edge. Tiến trình PHP của bạn giữ phần Ngôn ngữ đánh dấu siêu văn bản (HTML), còn Cloudflare Worker chạy trình duyệt không giao diện. Gói này cung cấp trình kết xuất HTML dựa trên Worker (CloudflareHtmlRenderer) cùng các value object mà nó trả về, lớp bảo vệ yêu cầu cho các điểm cuối kết xuất (ApiProtection), dịch vụ lưu trữ R2 cho các tệp Định dạng tài liệu di động (PDF) đã kết xuất (R2ArchiveManager), và các trình trợ giúp truyền dữ liệu có ghim để tăng cường bảo mật cho Bảo mật tầng truyền tải (TLS) và Hệ thống tên miền (DNS). Cấu hình nằm trong ba đối tượng bất biến (CloudflareRendererConfig, ApiProtectionConfig, R2ArchiveConfig).
Để bắt đầu, hãy tạo một CloudflareRendererConfig, đưa nó vào CloudflareHtmlRenderer, rồi gọi render(). Lệnh gọi này gửi HTML của bạn tới Worker và trả về một CloudflareRenderResult chứa các byte PDF. Các lớp bảo vệ, lưu trữ và ghim đều được đặt xung quanh lệnh gọi đó.
Tác vụ thường gặp
Phần tiêu đề “Tác vụ thường gặp”Các đoạn mã này bao quát những quy trình bạn nhiều khả năng sẽ dùng nhất. Mỗi đoạn đều khép kín, đã được kiểm chứng đối chiếu với src/Cloudflare/, và đọc thông tin bí mật từ môi trường.
Kết xuất một chuỗi HTML thành PDF ở edge bằng lệnh gọi chuẩn:
<?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);}Tác dụng: gửi HTML tới Worker qua Giao thức truyền siêu văn bản bảo mật (HTTPS) và ghi các byte PDF khổ A4 trả về xuống đĩa sau khi isValid() xác nhận đó là tệp PDF hợp lệ.
Lưu trữ một tệp PDF đã kết xuất vào R2 và trả về một liên kết ngắn hạn:
<?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;Tác dụng: tải các byte PDF lên một khóa R2 được phân vùng theo ngày và, khi thành công, tạo một định vị tài nguyên thống nhất (URL) ký sẵn có hiệu lực 10 phút để tải xuống tạm thời.
Bảo vệ một điểm cuối kết xuất trước khi bắt đầu công việc Worker tốn kém:
<?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];}Tác dụng: xác thực khóa API và kích thước payload, kiểm tra giới hạn tốc độ theo từng client, rồi trả về quyết định cùng các tiêu đề phản hồi cần đính kèm khi yêu cầu bị từ chối.
Trình kết xuất
Phần tiêu đề “Trình kết xuất”Bảng này bao quát bề mặt trình kết xuất cốt lõi. Hãy dùng bảng này khi bạn tạo cấu hình, tạo trình kết xuất, hoặc thực hiện các lệnh gọi kết xuất và kiểm tra khả năng truy cập.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
new CloudflareRendererConfig(string $workerUrl, string $apiToken, int $renderTimeout = 30, string $defaultCss = '', int $maxHtmlSize = 5000000, ?string $r2FontBucket = null, bool $fallbackToLocal = true, array $pinnedPublicKeys = [], array $backupPublicKeys = []) | URL của Worker, bearer token, thời gian chờ, Bảng định kiểu phân tầng (CSS), giới hạn kích thước, bucket phông chữ R2 tùy chọn, cờ dự phòng, các tập ghim. | Dự phòng cục bộ được bật; ghim bị tắt khi các mảng ghim rỗng. | CloudflareRendererConfig | Không có dự kiến. | Hãy giữ bí mật API token; ưu tiên dùng URL Worker qua HTTPS. |
CloudflareRendererConfig::fromArray(array $config) | worker_url, api_token, render_timeout, default_css, max_html_size, r2_font_bucket, fallback_to_local, các mảng ghim. | Các khóa tùy chọn bị thiếu sẽ dùng giá trị mặc định của hàm khởi tạo. | CloudflareRendererConfig | Không có dự kiến. | Dùng với các mảng cấu hình theo kiểu framework. |
CloudflareRendererConfig::isValid() | không có. | Yêu cầu URL của Worker và API token không rỗng. | bool | Không có dự kiến. | Một cấu hình không hợp lệ sẽ kích hoạt dự phòng hoặc thất bại trong trình kết xuất. |
CloudflareRendererConfig::allPublicKeyPins() | không có. | Gộp các ghim khóa công khai chính và dự phòng. | list<string> | Không có dự kiến. | Danh sách rỗng sẽ vô hiệu hóa việc ghim. |
new CloudflareHtmlRenderer(CloudflareRendererConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?LocalRendererFactoryInterface $localRendererFactory = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null) | Cấu hình, các phụ thuộc Giao thức truyền siêu văn bản (HTTP) theo Khuyến nghị tiêu chuẩn PHP (PSR), logger tùy chọn, factory dự phòng cục bộ tùy chọn, chính sách HTML tùy chọn, response factory tùy chọn. | Dùng DefaultHtmlSecurityPolicy khi không cung cấp chính sách HTML. | CloudflareHtmlRenderer | Lỗi kết nối container. | Response factory bật phương thức truyền cURL được ghim khi cần. |
CloudflareHtmlRenderer::render(string $html, float $widthPt = 595.28, float $heightPt = 0, array $fontFiles = []) | HTML, chiều rộng trang, chiều cao trang, các tệp phông chữ trong R2. | Chiều rộng A4, chiều cao tự động, không có tệp phông chữ. | CloudflareRenderResult | CloudflareNotAvailableException, CloudflareRenderException, các lỗi xác thực. | Xác thực kích thước HTML và URL của Worker trước khi thực hiện input/output mạng (I/O). |
CloudflareHtmlRenderer::getHtmlSecurityPolicy() | không có. | Trả về chính sách lớp phân tích cú pháp đã cấu hình. | HtmlSecurityPolicyInterface | Không có dự kiến. | Dùng cùng với bảo vệ điểm cuối và xác thực URL của Worker. |
CloudflareHtmlRenderer::isAvailable() | không có. | Gửi yêu cầu HEAD tới Worker khi cấu hình hợp lệ. | bool | Trả về false khi có lỗi. | Dùng để kiểm tra mức độ sẵn sàng, không phải là biện pháp bảo vệ runtime duy nhất. |
Các value object của trình kết xuất và bảo mật
Phần tiêu đề “Các value object của trình kết xuất và bảo mật”Dùng bảng này cho các value object yêu cầu và kết quả (CloudflareRenderResult, CloudflareRenderPayload) cùng các kiểm tra tầng truyền tải tĩnh để xác thực HTML, URL của Worker và các ghim DNS trước khi thực hiện I/O mạng.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
new CloudflareRenderResult(string $pdfData, float $widthPt, float $heightPt, float $contentHeightPx = 0.0, string $renderLocation = '', float $renderTimeMs = 0.0) | Các byte PDF, chiều rộng, chiều cao, chiều cao nội dung đo được, vị trí edge, thời gian kết xuất. | Siêu dữ liệu rỗng khi Worker không báo cáo. | CloudflareRenderResult | Không có dự kiến. | Thường được trả về bởi CloudflareResponseParser::parse(). |
CloudflareRenderResult::isValid() | không có. | Kiểm tra các byte PDF không rỗng và bắt đầu bằng một tiêu đề PDF. | bool | Không có dự kiến. | Dùng trước khi lưu trữ hoặc chuyển các byte sang lớp khác. |
CloudflareRenderResult::size() | không có. | Đếm các byte PDF đã kết xuất. | int | Không có dự kiến. | Đưa vào logic hạn ngạch và kiểm toán. |
new CloudflareRenderPayload(string $html, float $widthPt, float $heightPt = 0, string $defaultCss = '', ?string $r2FontBucket = null, array $fontFiles = []) | HTML, kích thước, CSS, bucket phông chữ R2 tùy chọn, danh sách tệp phông chữ. | Chiều cao tự động, không có CSS mặc định, không có bucket phông chữ R2, không có tệp phông chữ. | CloudflareRenderPayload | Không có dự kiến. | Value object cho payload của yêu cầu. |
CloudflareRenderPayload::toJson() | không có. | Tuần tự hóa HTML, kích thước, CSS và các tham chiếu phông chữ dưới dạng Ký hiệu đối tượng JavaScript (JSON) cho Worker. | string | Lỗi mã hóa JSON. | API payload yêu cầu cấp thấp. |
CloudflareResponseParser::parse(ResponseInterface $response, float $requestedWidthPt) | Phản hồi của Worker và chiều rộng được yêu cầu. | Chấp nhận phản hồi PDF nhị phân và phản hồi JSON có cấu trúc. | CloudflareRenderResult | CloudflareRenderException cho đầu ra Worker thất bại hoặc không hợp lệ. | Trình phân tích cú pháp trung tâm mà trình kết xuất sử dụng. |
CloudflareSecurityPolicy::validate(string $html, int $maxSize) | Đầu vào HTML và giới hạn kích thước. | Áp dụng chính sách đầu vào HTML của gói. | void | Ngoại lệ xác thực. | Hãy giữ các kiểm tra đầu vào không đáng tin cậy ở bên ngoài ranh giới Worker. |
CloudflareSecurityPolicy::validateWorkerUrl(string $url) | URL của Worker. | Phân tích cú pháp và xác thực đích đến. | array | Ngoại lệ xác thực. | Chặn các dạng điểm cuối không an toàn trước khi thực hiện I/O mạng. |
CloudflareSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps) | Host và danh sách IP được ghim. | Xác minh các ghim DNS dự kiến. | void | Ngoại lệ xác thực khi các ghim đã cũ hoặc không hợp lệ. | Dùng trong các kiểm tra vận hành cho các triển khai có ghim. |
Bảo vệ API
Phần tiêu đề “Bảo vệ API”Dùng bảng này khi bạn bảo vệ một điểm cuối kết xuất: xác thực khóa API, kiểm tra kích thước payload và giới hạn tốc độ, cùng các đối tượng kết quả và tiêu đề được tạo ra.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
new ApiProtection(ApiProtectionConfig $config, ?ApiKeyValidator $keyValidator = null, ?Closure $clock = null) | Cấu hình bảo vệ, trình xác thực khóa tùy chọn, đồng hồ tùy chọn. | Dùng thời gian hệ thống khi không cung cấp đồng hồ. | ApiProtection | Không có dự kiến. | Truyền vào một đồng hồ tất định trong các bài kiểm thử. |
ApiProtection::checkRequest(string $clientId, int $payloadSize, string $apiKey = '') | Định danh client, kích thước payload, khóa API tùy chọn. | Khóa API rỗng chỉ được chấp nhận khi cấu hình không yêu cầu khóa. | ApiProtectionResult | Không có dự kiến. | Kiểm tra khóa API và kích thước, sau đó giới hạn tốc độ. |
ApiProtection::getRateLimit(string $clientId) | Định danh client. | Không ghi nhận một yêu cầu. | RateLimitResult | Không có dự kiến. | Dùng để thêm các tiêu đề giới hạn tốc độ. |
new ApiKeyValidator(array $validKeys = []) | Danh sách các khóa văn bản thuần hợp lệ. | Danh sách rỗng sẽ từ chối tất cả các khóa. | ApiKeyValidator | Không có dự kiến. | Hãy lưu thông tin bí mật bên ngoài mã và nạp qua cấu hình. |
ApiKeyValidator::validate(string $key) | Khóa thô. | So sánh với các khóa văn bản thuần đã cấu hình bằng logic an toàn về thời gian. | bool | Không có dự kiến. | Tham số này nhạy cảm; không ghi log khóa thô. |
ApiKeyValidator::addKey(string $key) | Khóa thô. | Thêm một khóa đã băm vào một thực thể trình xác thực mới. | self | Không có dự kiến. | Hãy xem thực thể được trả về là trình xác thực đã cập nhật. |
ApiKeyValidator::revokeKey(string $key) | Khóa thô. | Loại bỏ giá trị băm khớp khỏi một thực thể trình xác thực mới. | self | Không có dự kiến. | Hãy xem thực thể được trả về là trình xác thực đã cập nhật. |
ApiKeyValidator::hashKey(string $key) | Khóa thô. | Tạo ra dạng băm được lưu trữ. | string | Không có dự kiến. | Không để lộ các giá trị băm trong log hoặc trong phản hồi gửi cho client. |
ApiKeyValidator::validateHashed(string $key, array $hashedKeys) | Khóa thô và các ứng viên băm. | So sánh với các giá trị băm được cung cấp trong thời gian hằng số. | bool | Không có dự kiến. | Trình trợ giúp cấp thấp cho kho khóa tùy chỉnh. |
new ApiProtectionConfig(int $maxRequestsPerMinute = 60, int $maxRequestsPerHour = 1000, int $maxPayloadSizeBytes = 10485760, array $allowedOrigins = [], bool $requireApiKey = true, string $apiKeyHeader = 'X-Api-Key', int $rateLimitWindowSeconds = 60) | Giới hạn yêu cầu, giới hạn payload, nguồn gốc được phép, yêu cầu khóa API, tên tiêu đề, độ dài cửa sổ. | 60/minute, 1000/hour, payload 10 MiB, yêu cầu khóa API. | ApiProtectionConfig | Không có dự kiến. | Dựng trực tiếp trong các bài kiểm thử hoặc nạp bằng 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. | Các khóa bị thiếu sẽ dùng giá trị mặc định của hàm khởi tạo. | ApiProtectionConfig | Không có dự kiến. | Dùng để nạp cấu hình framework. |
ApiProtectionConfig::isValid() | không có. | Yêu cầu các giới hạn dương cùng các giá trị kích thước và cửa sổ nhất quán. | bool | Không có dự kiến. | Hãy xác thực trước khi đưa một điểm cuối ra ngoài. |
new ApiProtectionResult(bool $allowed, string $denialReason = '', ?RateLimitResult $rateLimit = null) | Quyết định, lý do từ chối, kết quả giới hạn tốc độ tùy chọn. | Lý do từ chối rỗng và không có kết quả giới hạn tốc độ. | ApiProtectionResult | Không có dự kiến. | Được trả về bởi ApiProtection::checkRequest(). |
ApiProtectionResult::toHeaders() | không có. | Phát ra các tiêu đề giới hạn tốc độ khi tồn tại dữ liệu tốc độ. | array<string, string> | Không có dự kiến. | Đính kèm vào các phản hồi của Worker hoặc của framework. |
new RateLimitResult(bool $allowed, int $remainingRequests, int $retryAfterSeconds, string $clientId) | Quyết định, số lượng còn lại, độ trễ thử lại, định danh client (ID). | Không có giá trị mặc định. | RateLimitResult | Không có dự kiến. | Kết quả bất biến cho một lượt kiểm tra. |
RateLimitResult::toHeaders() | không có. | Phát ra các tiêu đề giới hạn còn lại và đặt lại. | array<string, string> | Không có dự kiến. | Dùng cho quan sát và khoảng chờ thử lại của client. |
new RateLimitEntry(string $clientId, int $requestCount = 0, int $windowStart = 0, int $hourlyCount = 0, int $hourlyWindowStart = 0) | ID client và các bộ đếm có thể thay đổi. | Các bộ đếm bắt đầu từ không. | RateLimitEntry | Không có dự kiến. | Đối tượng theo dõi trong bộ nhớ. |
RateLimitEntry::increment() | không có. | Tăng bộ đếm trong bộ nhớ cho một client/window. | void | Không có dự kiến. | Trình trợ giúp cấp thấp được ApiProtection sử dụng. |
RateLimitEntry::isExpired(int $windowSeconds) | Độ dài cửa sổ tính bằng giây. | So sánh với thời gian hiện tại. | bool | Không có dự kiến. | Trình trợ giúp xác định hết hạn lúc runtime. |
RateLimitEntry::isExpiredAt(int $now, int $windowSeconds) | Giá trị đồng hồ và độ dài cửa sổ. | So sánh với giá trị đồng hồ được cung cấp. | bool | Không có dự kiến. | Trình trợ giúp kiểm thử tất định. |
RateLimitEntry::reset() | không có. | Đặt lại số đếm và thời điểm bắt đầu cửa sổ. | void | Không có dự kiến. | Dùng khi một cửa sổ mới bắt đầu. |
Kho R2
Phần tiêu đề “Kho R2”Dùng bảng này khi bạn lưu các tệp PDF đã kết xuất trong Cloudflare R2: dịch vụ lưu trữ, các kiểu cấu hình và khóa đối tượng của nó, cùng kết quả tải lên cần kiểm tra trước khi bạn cấp URL.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
new R2ArchiveManager(R2ArchiveConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory) | Cấu hình R2 và các factories/client. HTTP theo PSR. | Không có lệnh gọi mạng nào trong lúc khởi tạo. | R2ArchiveManager | Lỗi kết nối container. | Dịch vụ lưu trữ chính. |
R2ArchiveManager::upload(string $pdfData, string $filename, array $metadata = []) | Các byte PDF thô, tên tệp gốc, siêu dữ liệu dạng chuỗi. | Siêu dữ liệu rỗng; khóa được phân vùng theo ngày. | R2UploadResult | Trả về kết quả không thành công khi cấu hình, kích thước, HTTP hoặc truyền dữ liệu thất bại. | Không ném ngoại lệ cho các lỗi tải lên thông thường. |
R2ArchiveManager::generateSignedUrl(string $key, int $expiresInSeconds = 3600) | Khóa đối tượng và thời gian tồn tại (TTL) của URL. | URL đã ký có hiệu lực một giờ. | string | Lỗi ký do cấu hình không hợp lệ. | Dùng TTL ngắn cho các tệp PDF nhạy cảm. |
R2ArchiveManager::buildObjectKey(string $filename) | Tên tệp gốc. | Dùng tiền tố đường dẫn đã cấu hình và ngày hiện tại. | R2ObjectKey | Không có dự kiến. | Dùng để phân vùng kho theo cách có thể dự đoán được. |
R2ArchiveManager::createPutRequest(R2ObjectKey $key, string $data, array $metadata = []) | Khóa đối tượng, các byte thô, siêu dữ liệu. | Ký một yêu cầu PUT. | RequestInterface | Lỗi dựng yêu cầu. | API cấp thấp cho các phương thức truyền tùy chỉnh. |
new R2ArchiveConfig(string $bucketName, string $accountId, string $accessKeyId, string $secretAccessKey, string $endpoint = '', string $pathPrefix = 'pdfs/', int $maxFileSizeBytes = 104857600) | Bucket, ID tài khoản, thông tin xác thực, endpoint thay thế, tiền tố khóa, kích thước đối tượng tối đa. | Suy ra endpoint, dùng tiền tố pdfs/, kích thước đối tượng tối đa 100 MiB. | R2ArchiveConfig | InvalidArgumentException cho tên bucket không hợp lệ. | Hãy coi thông tin xác thực là cấu hình chứa thông tin bí mật. |
R2ArchiveConfig::fromArray(array $data) | ID tài khoản, bucket, thông tin xác thực, tiền tố đường dẫn, endpoint thay thế, kích thước tối đa. | Các giá trị bị thiếu sẽ dùng giá trị mặc định của hàm khởi tạo. | R2ArchiveConfig | Tên bucket không hợp lệ khi được cung cấp. | Dùng để nạp cấu hình ứng dụng. |
R2ArchiveConfig::isValid() | không có. | Yêu cầu tài khoản, bucket, access key và secret key không rỗng. | bool | Không có dự kiến. | Cấu hình không hợp lệ khiến tải lên thất bại kèm kết quả có cấu trúc. |
R2ArchiveConfig::getEndpoint() | không có. | Dùng endpoint tường minh hoặc suy ra endpoint Cloudflare R2 từ ID tài khoản. | string | Không có dự kiến. | Dùng để dựng yêu cầu đã ký. |
new R2ObjectKey(string $key, string $bucket) | Khóa đối tượng đầy đủ và bucket. | Không chuẩn hóa. | R2ObjectKey | Không có dự kiến. | Thường được tạo bởi R2ObjectKey::generate(). |
R2ObjectKey::generate(string $prefix, string $filename, ?DateTimeInterface $date = null) | Tiền tố, tên tệp gốc, ngày tùy chọn. | Khóa đối tượng được phân vùng theo ngày và đã được làm sạch. | R2ObjectKey | Không có dự kiến. | Truyền ngày vào trong các bài kiểm thử để có khóa tất định. |
R2ObjectKey::fullPath() | không có. | Nối đường dẫn phân vùng và tên tệp đối tượng. | string | Không có dự kiến. | Lưu giá trị này làm khóa đối tượng. |
new R2UploadResult(bool $success, string $key, string $etag = '', int $size = 0, string $error = '') | Cờ thành công, khóa đối tượng, thẻ thực thể (ETag), kích thước byte, thông báo lỗi. | ETag rỗng, kích thước bằng không, lỗi rỗng. | R2UploadResult | Không có dự kiến. | Do R2ArchiveManager::upload() trả về. |
R2UploadResult::isValid() | không có. | Hợp lệ khi việc tải lên thành công và có cả khóa lẫn ETag. | bool | Không có dự kiến. | Kiểm tra trước khi cấp URL. |
R2UploadResult::publicUrl(string $customDomain = '') | Miền công khai tùy chỉnh tùy chọn. | Trả về khóa đối tượng trần khi không cung cấp miền tùy chỉnh. | string | Không có dự kiến. | Tránh dùng URL công khai cho tài liệu nhạy cảm trừ khi chính sách cho phép. |
Các trình trợ giúp truyền dữ liệu
Phần tiêu đề “Các trình trợ giúp truyền dữ liệu”Chỉ dùng bảng này cho kết nối cấp thấp: ghim Giao thức Internet (IP) và SubjectPublicKeyInfo (SPKI) ở mức cURL, cùng các hợp đồng trình kết xuất cục bộ được dùng làm đường dự phòng khi không truy cập được Worker.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném ra hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30) | Các factory PSR-17, các IP được ghim, các khóa công khai được ghim, thời gian chờ. | Không có ghim và thời gian chờ 30 giây. | PinnedCurlTransport | Không có dự kiến. | Chỉ dùng khi cần ghim ở mức cURL. |
PinnedCurlTransport::sendRequest(RequestInterface $request) | Yêu cầu PSR-7. | Gửi qua cURL với thời gian chờ và các điều khiển ghim đã cấu hình. | ResponseInterface | Các ngoại lệ truyền dữ liệu PSR-18. | Chỉ dùng khi HTTP client của framework không thể áp dụng cùng chính sách ghim đó. |
PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port) | Yêu cầu, host đích, cổng đích. | Dựng mảng tùy chọn cURL được sendRequest() sử dụng. | array | Lỗi yêu cầu không hợp lệ hoặc lỗi cấu hình ghim. | Hook kiểm thử và chẩn đoán cấp thấp. |
LocalRendererInterface::render(string $html, array $options = []) | HTML và các tùy chọn của trình kết xuất. | Chỉ là hợp đồng; phần triển khai đặt các giá trị mặc định. | string | Các lỗi kết xuất đặc thù theo phần triển khai. | Dùng làm dự phòng cục bộ khi không thể kết xuất bằng Worker. |
LocalRendererFactoryInterface::create() | không có. | Tạo một phần triển khai trình kết xuất cục bộ. | LocalRendererInterface | Lỗi factory hoặc lỗi phụ thuộc. | Giữ việc dựng trình kết xuất dự phòng bên ngoài CloudflareHtmlRenderer. |
Ghi chú phát triển
Phần tiêu đề “Ghi chú phát triển”- Hãy coi URL của Worker là ranh giới mạng. Hãy xác thực đích đến, kích thước và danh tính trước khi kết xuất.
- Hãy dùng các kết quả bảo vệ API làm đầu ra chính sách, không dùng ngoại lệ làm luồng điều khiển.
- Các lần tải lên R2 trả về kết quả thành công hoặc lỗi có cấu trúc; hãy xử lý cả hai nhánh.