Integrasi Cloudflare untuk NextPDF

Sekilas

Halaman ini menunjukkan alur Cloudflare secara lengkap: memasang paket, mengonfigurasi, merender berkas Portable Document Format (PDF), dan secara opsional mengarsipkan hasilnya. Setiap langkah mengirimkan proses rendering melalui Cloudflare Worker dan R2. Gunakan panduan ini bersama halaman konseptual /integrations/cloudflare/overview/ dan rujukan /integrations/cloudflare/configuration/.

Pemasangan

composer require nextpdf/cloudflare:^0.1

Selanjutnya, tambahkan klien PHP Standards Recommendation (PSR)-18 dan factory PSR-17, misalnya Guzzle 7. Paket ini hanya mendeklarasikan kontrak PSR dan tidak menyertakan klien konkret, sehingga Anda harus menyediakannya sendiri. Untuk detail lengkap, lihat /integrations/cloudflare/install/.

Boot/penemuan otomatis

Bridge ini tidak menyertakan service provider ataupun bundle. Buat instance langsung dari kolaborator PSR dan sebuah CloudflareRendererConfig. Framework host Anda sebaiknya mengikatnya di dalam container dengan memakai ulang binding PSR-18 aplikasi yang sudah ada. Untuk urutan boot lengkap dan contoh binding container, lihat /integrations/cloudflare/boot-and-discovery/.

Binding container

Daftarkan CloudflareHtmlRenderer sebagai singleton. Berikan klien PSR-18, factory request dan stream PSR-17, serta logger PSR-3 opsional. Jika Anda menggunakan transport cURL yang di-pin, berikan juga factory response PSR-17. Lihat contoh binding di /integrations/cloudflare/boot-and-discovery/.

Publikasikan konfigurasi

Paket ini membaca pengaturan dari sebuah CloudflareRendererConfig. Muat secret dari environment; jangan pernah memuatnya dari berkas yang di-commit:

<?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 harus menggunakan skema Hypertext Transfer Protocol Secure (HTTPS). apiToken bersifat #[SensitiveParameter]. Untuk rujukan lengkap setiap field, lihat /integrations/cloudflare/configuration/, yang mencakup field pin Subject Public Key Info (SPKI) dan setiap nilai default. Konfigurasi pengarsipan R2 dan lapisan proteksi API dibahas di /integrations/cloudflare/production-usage/.

Smoke test service provider/bundle

Tidak ada service provider yang perlu menjalani smoke test. Gunakan pemeriksaan boot berikut sebagai gantinya:

$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() hanya memeriksa kelengkapan dan tidak melakukan panggilan jaringan. isAvailable() melakukan HEAD terautentikasi. Fungsi ini mengembalikan false tanpa melempar eksepsi ketika Worker tidak tersedia.

Titik masuk API publik

Paket ini mengekspos permukaan publik berikut di bawah NextPDF\Cloudflare\:

Tipe	Peran
`CloudflareHtmlRenderer`	Titik masuk render: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	Konfigurasi renderer (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Hasil render bertipe (`isValid()`, `size()`).
`CloudflareRenderPayload`	Payload Worker dalam JavaScript Object Notation (JSON) (`toJson()`).
`CloudflareResponseParser`	Parser response Worker → hasil.
`CloudflareSecurityPolicy`	Validasi input dan URL.
`Transport\PinnedCurlTransport`	Transport PSR-18 dengan pin Domain Name System (DNS) / Transport Layer Security (TLS).
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Kontrak fallback lokal.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Proteksi API masuk.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	Pengarsipan R2.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	Hierarki eksepsi.

Untuk panduan rendering lengkap, lihat /integrations/cloudflare/quickstart/. Untuk pemasangan produksi, lihat /integrations/cloudflare/production-usage/, yang mencakup fallback, telemetri, pengarsipan, dan proteksi.

Lihat juga

/integrations/cloudflare/overview/ — batas kepercayaan dan model rendering di edge.
/integrations/cloudflare/quickstart/ — render pertama yang dapat dijalankan.
/integrations/cloudflare/boot-and-discovery/ — detail pemasangan container.
/integrations/cloudflare/security-and-operations/ — pertahanan server-side request forgery (SSRF), pinning, dan runbook operasional.
/integrations/cloudflare/troubleshooting/ — mode kegagalan yang dipetakan ke eksepsi.