NextPDF Cloudflare entegrasyonu

Bir bakışta

Bu sayfa, Cloudflare iş akışını uçtan uca gösterir: paketi kurun, yapılandırın, bir Taşınabilir belge biçimi (PDF) dosyasını işleyin ve isteğe bağlı olarak sonucu arşivleyin. Her adımda işleme, bir Cloudflare Worker ve R2 üzerinden yönlendirilir. Bu nasıl yapılır kılavuzunu, kavramsal /integrations/cloudflare/overview/ ve başvuru niteliğindeki /integrations/cloudflare/configuration/ ile birlikte kullanın.

Kurulum

composer require nextpdf/cloudflare:^0.1

Ardından, Guzzle 7 gibi bir PHP standartları önerisi (PSR)-18 istemcisi ve PSR-17 fabrikaları ekleyin. Paket yalnızca PSR sözleşmelerini bildirir ve somut bir istemci içermez; bu nedenle istemciyi sizin sağlamanız gerekir. Tüm ayrıntılar için bkz. /integrations/cloudflare/install/.

Önyükleme/otomatik keşif

Köprü, bir hizmet sağlayıcı veya paket içermez. Köprüyü doğrudan PSR bileşenleri ve bir CloudflareRendererConfig nesnesiyle oluşturun. Ana çerçeveniz, uygulamanın mevcut PSR-18 bağlamasını yeniden kullanarak köprüyü kendi kapsayıcısına bağlamalıdır. Tam önyükleme sırası ve örnek kapsayıcı bağlaması için bkz. /integrations/cloudflare/boot-and-discovery/.

Kapsayıcı bağlamaları

Önce CloudflareHtmlRenderer sınıfını singleton olarak bağlayın. PSR-18 istemcisini, PSR-17 istek ve akış fabrikalarını ve isteğe bağlı bir PSR-3 günlükleyicisini iletin. Sabitlenmiş cURL taşıyıcısını kullandığınızda ayrıca bir PSR-17 yanıt fabrikası iletin. Bağlama örneği için bkz. /integrations/cloudflare/boot-and-discovery/.

Yapılandırmayı yayımlama

Paket, ayarları bir CloudflareRendererConfig nesnesinden okur. Gizli bilgileri ortamdan yükleyin; bunları asla commit edilmiş dosyalardan yüklemeyin:

<?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 değeri, Güvenli köprü metni aktarım protokolü (HTTPS) şemasını kullanmalıdır. apiToken, #[SensitiveParameter] olarak işaretlenmiştir. Tüm alanlara ilişkin başvuru için, konu açık anahtar bilgileri (SPKI) sabitleme alanlarını ve tüm varsayılanları kapsayan /integrations/cloudflare/configuration/ sayfasına bakın. R2 arşivleme yapılandırması ve uygulama programlama arayüzü (API) koruma katmanı /integrations/cloudflare/production-usage/ sayfasında ele alınır.

Hizmet sağlayıcı/paket duman testi

Duman testinden geçirilecek bir hizmet sağlayıcı yoktur. Bunun yerine şu önyükleme denetimini kullanın:

$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() yalnızca eksiksizlik denetimi yapar ve herhangi bir ağ çağrısı gerçekleştirmez. isAvailable(), kimliği doğrulanmış bir HEAD isteği gerçekleştirir. Worker çalışır durumda değilse, istisna fırlatmadan false döndürür.

Genel API giriş noktaları

Paket, NextPDF\Cloudflare\ altında şu genel API yüzeyini sunar:

Tür	Rol
`CloudflareHtmlRenderer`	İşleme giriş noktası: `render()`, `isAvailable()`, `getHtmlSecurityPolicy()`.
`CloudflareRendererConfig`	İşleyici yapılandırması (`fromArray()`, `isValid()`, `allPublicKeyPins()`).
`CloudflareRenderResult`	Tipli işleme sonucu (`isValid()`, `size()`).
`CloudflareRenderPayload`	Worker JavaScript nesne gösterimi (JSON) yükü (`toJson()`).
`CloudflareResponseParser`	Worker yanıtı → sonuç ayrıştırıcısı.
`CloudflareSecurityPolicy`	Girdi ve URL doğrulaması.
`Transport\PinnedCurlTransport`	Alan adı sistemi (DNS) ve taşıma katmanı güvenliği (TLS) sabitlemeli PSR-18 taşıyıcısı.
`Contract\LocalRendererFactoryInterface`, `Contract\LocalRendererInterface`	Yerel yedek sözleşmeleri.
`ApiProtection`, `ApiProtectionConfig`, `ApiProtectionResult`, `ApiKeyValidator`	Gelen API koruması.
`R2ArchiveManager`, `R2ArchiveConfig`, `R2ObjectKey`, `R2UploadResult`	R2 arşivleme.
`Exception\CloudflareRenderException`, `Exception\CloudflareNotAvailableException`, `Exception\InvalidSpkiPinException`	İstisna hiyerarşisi.

Eksiksiz bir adım adım işleme kılavuzu için bkz. /integrations/cloudflare/quickstart/. Üretim ortamındaki bağlantılar için yedekleme, telemetri, arşivleme ve korumayı kapsayan /integrations/cloudflare/production-usage/ sayfasına bakın.

Ayrıca bkz.

/integrations/cloudflare/overview/ — güven sınırı ve uçta işleme modeli.
/integrations/cloudflare/quickstart/ — çalıştırılabilir bir ilk işleme.
/integrations/cloudflare/boot-and-discovery/ — kapsayıcı bağlama ayrıntıları.
/integrations/cloudflare/security-and-operations/ — sunucu tarafı istek sahteciliği (SSRF) savunması, sabitleme ve operasyonel kılavuz.
/integrations/cloudflare/troubleshooting/ — istisnalara eşlenen hata modları.