Cloudflare için geliştirici kılavuzu

Bir bakışta

Cloudflare paketi, Taşınabilir Belge Biçimi (PDF) işlemeyi bir Worker sınırına taşır. Worker işleme, yerel yedek, API koruması ve R2 arşivini, her biri kendi hata yönetimine sahip ayrı yetenekler olarak ele alın.

Kenar işleme hizmetleri, korumalı işleme uç noktaları, arşiv iş akışları veya yerel yedek yolları oluştururken bu kılavuzu nextpdf/cloudflare ile birlikte kullanın.

Mimari sınırı

Katman	Sahibi	Sorumluluk	Buraya koymayın
Uygulama uç noktası	Uygulama	Çağıranı yetkilendirin, işleme isteğini normalleştirin ve iş politikasını uygulayın.	Kodda saklanan Worker belirteçleri.
API koruması	nextpdf/cloudflare ve uygulama	API anahtarı denetimleri, yük boyutu denetimleri ve süreç içi hız sınırı kararları.	Faturalandırma, kiracı hakları veya kalıcı kota uygulaması.
Cloudflare işleyicisi	nextpdf/cloudflare	HTML’yi ve Worker URL’sini doğrulayın, işleme yükünü gönderin ve yanıtı ayrıştırın.	Şablon işleme veya etki alanı sorguları.
Worker	Uygulama dağıtımı	Browser Rendering’i çalıştırın ve PDF baytlarını ya da yapılandırılmış bir sonuç döndürün.	PHP tarafı depolama politikası.
Yerel yedek	Uygulama dağıtımı	Worker kullanılamadığında işleme yapın.	İşletim kesintilerini gizleyen sessiz yedek.
R2 arşivi	nextpdf/cloudflare	PDF dosyalarını karşıya yükleyin, nesne anahtarları ve imzalı URL’ler oluşturun.	Gözden geçirilmeden eklenen hassas iş meta verileri.

Çalışma zamanı yaşam döngüsü

Aşama	Davranış	Geliştirici eylemi
Yapılandırma oluşturma	Worker URL’sini, API belirtecini, zaman aşımlarını, boyut sınırlarını, yedeği ve sabitlemeleri yükler.	Gizli bilgileri dağıtım yapılandırmasında tutun.
İstek koruması	İsteğe bağlı ApiProtection, anahtarı, boyutu ve hız sınırını doğrular.	Maliyetli işleme çalışmasından önce çalıştırın.
İşleyici çağrısı	CloudflareHtmlRenderer HTML’yi ve Worker URL’sini doğrular, ardından JSON’u gönderir.	Worker kullanılamamasını ve işleme hatalarını ayrı ayrı ele alın.
Yanıt ayrıştırma	CloudflareResponseParser::parse() ikili PDF çıktısını veya yapılandırılmış JSON çıktısını kabul eder.	Geçersiz veya PDF olmayan çıktıyı reddedin.
Yerel yedek	İsteğe bağlı bir yerel işleyici, Worker hatasını ele alır.	Yerel işleyici fabrikasını yalnızca barındırma ortamı bunu desteklediğinde ekleyin.
R2 arşivi	R2ArchiveManager PDF baytlarını saklar ve imzalı URL’ler oluşturur.	Bilinçli olarak hassas bilgi saklamadığınız sürece meta verileri hassas olmayan bilgilerle sınırlı tutun.

Önerilen uygulama yapısı

Yol	Amaç
app/Pdf/Cloudflare/*	Uygulama tarafındaki CloudflareHtmlRenderer sarmalayıcıları.
app/Pdf/Workers/*	Worker isteği veri aktarım nesneleri (DTO’lar) ve uç noktaya özgü politika.
app/Pdf/Archive/*	R2 arşivi orkestrasyonu ve saklama kararları.
app/Pdf/Fallback/*	LocalRendererFactoryInterface, izin verilen yedek için uygulama.
tests/Pdf/Cloudflare/*	Worker kapalıyken çalışma, geçersiz belirteç, yük ve arşiv testleri.

PHP API belirtecini Worker belirtecinden ayrı tutun. PHP, Worker’a karşı kimliğini doğrular. Worker, tarayıcı çalışmasına başlamadan önce gelen isteklerin kimliğini doğrulamalıdır.

<?php

use NextPDF\Cloudflare\ApiProtection;
use NextPDF\Cloudflare\ApiProtectionConfig;
use NextPDF\Cloudflare\ApiKeyValidator;

$protection = new ApiProtection(
    new ApiProtectionConfig(maxRequestsPerMinute: 30),
    new ApiKeyValidator([$expectedApiKey]),
);

$result = $protection->checkRequest(
    clientId: $clientId,
    payloadSize: strlen($html),
    apiKey: $presentedApiKey,
);

if (!$result->allowed) {
    return new JsonResponse(['error' => $result->denialReason], 429, $result->toHeaders());
}

İşleyici deseni

İşleyiciyi, çerçevenizin sağladığı PSR-18 ve PSR-17 dahil PHP Standartları Önerisi (PSR) bağımlılıklarıyla oluşturun. Yerel yedeği açıkça belirtin; böylece işletim ekipleri sistemin Worker’ı kullanmayı ne zaman bıraktığını görebilir.

<?php

use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;

$renderer = new CloudflareHtmlRenderer(
    config: CloudflareRendererConfig::fromArray([
        'worker_url' => getenv('NEXTPDF_CLOUDFLARE_WORKER_URL'),
        'api_token' => getenv('NEXTPDF_CLOUDFLARE_API_TOKEN'),
        'render_timeout' => 30,
        'max_html_size' => 1_000_000,
        'fallback_to_local' => false,
    ]),
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
);

$rendered = $renderer->render($html, widthPt: 595.28);

R2 arşiv deseni

Yalnızca işleme başarılı olduktan ve politika sonucu kabul ettikten sonra arşivleyin. Genel URL’leri ve imzalı URL’leri ayrı kararlar olarak değerlendirin.

<?php

use NextPDF\Cloudflare\R2ArchiveManager;

$upload = $archive->upload(
    pdfData: $rendered->pdfData,
    filename: 'invoice-1234.pdf',
    metadata: [
        'document_type' => 'invoice',
    ],
);

if ($upload->isValid()) {
    $temporaryUrl = $archive->generateSignedUrl($upload->key, 600);
}

Saklama ve erişim politikanız açıkça izin vermediği sürece nesne meta verilerine müşteri adlarını, e-posta adreslerini, fatura toplamlarını veya düzenlemeye tabi tanımlayıcıları koymayın.

Genişletme noktaları

Genişletme noktası	Şunun için kullanın	Kısıtlama
LocalRendererFactoryInterface	Artisan veya başka bir işleyici üzerinden yerel yedek.	Mutlaka LocalRendererInterface arabirimini uygulayan bir nesne döndürmelidir.
ApiProtectionConfig	API anahtarı, yük boyutu ve hız sınırı politikası.	Bellek içi sınırlar her süreç için geçerlidir.
ApiKeyValidator	Zamanlama açısından güvenli anahtar doğrulama ve anahtar döndürme yardımcıları.	Gizli bilgileri kaynak kodunun dışında saklayın.
R2ArchiveConfig	Paket, kimlik bilgileri, yol öneki, uç nokta ve boyut sınırları.	Kimlik bilgileri asla günlüğe kaydedilmemelidir.
PinnedCurlTransport	İnternet Protokolü (IP) ve Konu Genel Anahtar Bilgisi (SPKI) sabitleme uygulaması.	cURL etkin bir çalışma zamanı ve yanıt fabrikası gerektirir.
CloudflareResponseParser	Worker yanıtını ayrıştırma.	Geçersiz PDF çıktısını veya hata yanıtlarını reddeder.

Geliştirme iş akışı

1. Önce yerel bir işleme yolu oluşturun.
2. Küçük ve temsili bir HTML örneğiyle Worker işlemesini ekleyin.
3. Genel uç noktaları açığa çıkarmadan önce istek korumasını etkinleştirin.
4. R2 yüklemesini yalnızca işleme ve yanıt akışları kararlı hale geldikten sonra ekleyin.
5. Worker kapalı, geçersiz belirteç, aşırı büyük yük, hız sınırı ve R2 hatası yollarını test edin.
6. Worker işlemesini, yedek işlemesini, arşiv yüklemesini ve imzalı URL oluşturmayı birbirinden ayıran günlükler ekleyin.

Hata yönetimi

Hata	Nerede ele alınmalı	Önerilen yanıt
Eksik veya geçersiz API anahtarı	API koruma katmanında.	İsteği, işleme çalışması başlamadan önce reddedin.
Aşırı büyük yük	API korumasında veya işleyici doğrulamasında.	Worker çağrısı olmadan bir doğrulama hatası döndürün.
Güvenli olmayan Worker URL’si	İşleyici güvenlik politikasında.	Ağ G/Ç işlemi başlamadan önce yapılandırmayı veya isteği başarısız hale getirin.
Worker kullanılamıyor	İşleyici sınırında.	Açıkça tanımlı yedeği yalnızca izin verildiğinde kullanın; aksi takdirde görünür biçimde başarısız olun.
R2 yükleme hatası	Arşiv sınırında.	Arşiv isteğe bağlıysa PDF yanıtını döndürün; politika gereği arşiv zorunluysa başarısız olun.
Sabitleme döndürme hatası	Dağıtım ve işletimde.	Yedek sabitlemeler ve bir geri alma planıyla döndürün.

Güvenli varsayılanlar

Konu	Varsayılan	Ne zaman geçersiz kılınmalı
Yedek	Yapılandırma varsayılanına göre etkin.	Yerel işleme dağıtım yalıtımını ihlal edecekse devre dışı bırakın.
En büyük HTML boyutu	5,000,000 bayt.	Genel uç noktalar için düşürün.
İmzalı URL yaşam süresi (TTL)	3600 saniye.	Hassas PDF’ler için kısaltın.
Sabitleme kümeleri	Boş.	Sabitlemeleri yalnızca bir döndürme planı ve yedek sabitlemelerle ekleyin.
API anahtarı gereksinimi	Koruma yapılandırması varsayılanına göre etkin.	Yalnızca özel, halihazırda kimliği doğrulanmış dahili çağrılar için devre dışı bırakın.

Test denetim listesi

• İşleyici testleri geçerli HTML, aşırı büyük HTML, geçersiz Worker URL’si ve Worker hata yanıtını kapsar.
• API koruma testleri eksik anahtarı, geçersiz anahtarı, çok büyük bir yükü ve aşılan bir hız sınırını kapsar.
• R2 testleri başarılı yüklemeyi, çok büyük yüklemeyi, başarısız HTTP durumunu, geçersiz paketi ve imzalı URL oluşturmayı kapsar.
• Yedek testleri, yerel işleyici yolunun açıkça tanımlı ve gözlemlenebilir olduğunu doğrular.
• Aktarım testleri sabitlenmiş IP’leri, genel anahtar sabitlemelerini, zaman aşımını ve politika gereği devre dışı bırakılan yönlendirmeleri kapsar.
• Gözlemlenebilirlik testleri işleme, yedek, arşiv ve imzalı URL oluşturma için ayrı günlük olaylarını doğrular.