NextPDF Cloudflare köprüsünün yapılandırması

Bir bakışta

Paketi üç değişmez yapılandırma nesnesi yönetir. Bu sayfadaki her varsayılan, src/Cloudflare/ içindeki ilgili kurucu imzasından okunur; bir belirtimden veya tahminden alınmaz. Bu sayfada bir üst sınır belirtildiğinde, o üst sınır bu paketin uyguladığı sınırdır. Cloudflare platform kapasitesi hakkında bir iddia değildir.

CloudflareRendererConfig

İşleyicinin yapılandırması. final readonly. Doğrudan veya CloudflareRendererConfig::fromArray() ile oluşturun.

Alan	Tür	Varsayılan	Anlamı
workerUrl	string	— (zorunlu)	Worker uç noktası URL’si. HTTPS kullanmalıdır.
apiToken	string	— (zorunlu)	Taşıyıcı (bearer) belirteci. #[SensitiveParameter] olarak işaretlidir.
renderTimeout	int	30	Sabitlenmiş cURL taşımasının uyguladığı, saniye cinsinden aktarım zaman aşımı.
defaultCss	string	''	HTML’nizden önce yüke eklenen CSS.
maxHtmlSize	int	5000000	İstek gönderilmeden önce uygulanan, bayt cinsinden en büyük HTML girdisi boyutu.
r2FontBucket	?string	null	Özel yazı tipi paketleri için R2 bucket adı.
fallbackToLocal	bool	true	Erişilemeyen bir Worker’ın yerel işleyiciye geri dönüp dönmeyeceği.
pinnedPublicKeys	list<string>	[]	SHA-256 SPKI parmak izleri, biçim sha256/<base64>.
backupPublicKeys	list<string>	[]	Yedek SPKI sabitlemeleri; döndürme bağımsız olarak doğrulanabilsin diye ayrı tutulurlar.

isValid() yalnızca şu koşullarda true döndürür: workerUrl !== '' ve apiToken !== ''. allPublicKeyPins(), pinnedPublicKeys ile backupPublicKeys birleşiminin yinelenmemiş halini döndürür. TLS katmanı, SPKI karması bu birleşimin herhangi bir üyesinde bulunan bir sertifikayı kabul eder. Bu davranış, sunulan SPKI parmak izi kümesi sabitlenmiş kümeyle kesiştiğinde sabitlenmiş bağlantıyı doğrulayan RFC 7469 §2.6 ile uyumludur. RFC 7469 §2.5, yedek sabitlemeyi istenmeyen sabitleme doğrulama hatasına karşı birincil kurtarma mekanizması olarak tanımlar. Sertifika döndürme işlemi uç noktayı bozmasın diye en az bir yedek sabitleme tutun — bkz. /integrations/cloudflare/security-and-operations/.

fromArray() anahtar eşlemesi

CloudflareRendererConfig::fromArray(), snake_case anahtarlarını okur ve bir anahtar eksikse ya da türü yanlışsa aynı varsayılanları uygular:

Dizi anahtarı	Eşlendiği alan
worker_url	workerUrl
api_token	apiToken
render_timeout	renderTimeout (varsayılan 30)
default_css	defaultCss
max_html_size	maxHtmlSize (varsayılan 5000000)
r2_font_bucket	r2FontBucket
fallback_to_local	fallbackToLocal (varsayılan true)
pinned_public_keys	pinnedPublicKeys (dize olmayan üyeler atılır)
backup_public_keys	backupPublicKeys (dize olmayan üyeler atılır)

<?php

declare(strict_types=1);

use NextPDF\Cloudflare\CloudflareRendererConfig;

$config = CloudflareRendererConfig::fromArray([
    'worker_url'     => 'https://pdf-renderer.example.workers.dev/render',
    'api_token'      => getenv('CF_PDF_TOKEN') ?: '',
    'render_timeout' => 60,
    'r2_font_bucket' => 'pdf-fonts',
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Paketin uyguladığı girdi boyutu sınırları

Bu sınırlar, herhangi bir istek süreçten ayrılmadan önce CloudflareSecurityPolicy::validate() tarafından uygulanır. Sayılar kaynaktan alınır:

Sınır	Değer	Nerede
En büyük HTML girdisi	maxHtmlSize (varsayılan 5000000 bayt)	CloudflareSecurityPolicy::validate()
En büyük çözülmüş base64 data-URI boyutu	13631488 bayt (≈13 MB)	CloudflareSecurityPolicy::MAX_DATA_URI_BYTES

İkisinden birinin aşılması, kuralı ihlal eden boyutu ve sınırı belirten bir iletiyle RuntimeException fırlatır. base64 üst sınırı, açma bombasına (decompression bomb) karşı koruma sağlar. İlke, çözülmüş boyutu base64 uzunluğundan tahmin eder ve üst sınırda ya da üzerinde reddeder. <meta http-equiv="refresh"> etiketi de büyük/küçük harfe duyarsız biçimde reddedilir; çünkü işlenen sayfanın içinden yönlendirme tetikleyebilir.

Paket yalnızca kendi uyguladığı sınırları belirtir. Worker’ın kendi istek, CPU veya bellek üst sınırları hakkında hiçbir iddiada bulunmaz. Bunlar için Cloudflare’in resmi belgelerine ve kendi Worker uygulamanıza başvurun.

ApiProtectionConfig

Bir Worker’ın — veya onun önündeki bir PHP ağ geçidinin — gelen işleme isteklerine uyguladığı isteğe bağlı istek koruma katmanının yapılandırması. final readonly.

Alan	Tür	Varsayılan	Anlamı
maxRequestsPerMinute	int	60	İstemci başına dakika başına istek üst sınırı.
maxRequestsPerHour	int	1000	İstemci başına saat başına istek üst sınırı.
maxPayloadSizeBytes	int	10485760	En büyük gelen yük (≈10 MB).
allowedOrigins	list<string>	[]	CORS izin listesi. Boş olması, burada hiçbir origin kısıtlamasının ifade edilmediği anlamına gelir.
requireApiKey	bool	true	Bir API anahtarının gerekli olup olmadığı.
apiKeyHeader	string	'X-Api-Key'	API anahtarını taşıyan başlık.
rateLimitWindowSeconds	int	60	Dakikalık pencerenin saniye cinsinden uzunluğu.

fromArray(), max_requests_per_minute, max_requests_per_hour, max_payload_size_bytes, allowed_origins, require_api_key, api_key_header ve rate_limit_window_seconds anahtarlarını okur. isValid(), her sayısal alanın pozitif olmasını ve apiKeyHeader alanının boş olmamasını gerektirir.

R2ArchiveConfig

İşlenen PDF’lerin S3 uyumlu API üzerinden Cloudflare R2’ye arşivlenmesine yönelik yapılandırma. final readonly.

Alan	Tür	Varsayılan	Anlamı
bucketName	string	— (zorunlu)	R2 bucket’ı. S3 adlandırma kuralına göre doğrulanır.
accountId	string	— (zorunlu)	Varsayılan uç noktayı oluşturmak için kullanılan Cloudflare hesap kimliği.
accessKeyId	string	— (zorunlu)	R2 erişim anahtarı kimliği. #[SensitiveParameter].
secretAccessKey	string	— (zorunlu)	R2 gizli erişim anahtarı. #[SensitiveParameter].
endpoint	string	''	Özel S3 uç noktası. Boş olması, varsayılanı accountId değerinden oluşturur.
pathPrefix	string	'pdfs/'	Yüklenen nesneler için anahtar öneki.
maxFileSizeBytes	int	104857600	Yüklemeden önce uygulanan en büyük yükleme boyutu (≈100 MB).

Kurucu, S3 uyumlu kurala uymayan ve boş olmayan bir bucketName değerini reddeder. Kural şudur: 3–63 karakter, küçük harf alfasayısal ve kısa çizgi, başta ve sonda bir alfasayısal karakter. İhlal durumunda InvalidArgumentException fırlatılır. isValid(), bucketName, accountId, accessKeyId ve secretAccessKey alanlarının boş olmamasını gerektirir. endpoint boş olduğunda getEndpoint(), https://<accountId>.r2.cloudflarestorage.com döndürür.

Gizli bilgi yönetimi

apiToken, accessKeyId ve secretAccessKey, #[SensitiveParameter] özniteliğini taşır; bu nedenle PHP bunları yığın izlerinden gizler. Bunları ortam değişkenlerinden veya bir gizli bilgi yöneticisinden sağlayın. Bunları asla commit etmeyin. Yapılandırma nesneleri değişmezdir; bu nedenle bir kez ayarlanan değer oluşturulduktan sonra değiştirilemez.

Ayrıca bkz.

• /integrations/cloudflare/quickstart/ — bu yapılandırmayı ilk işleme akışında uygulayın.
• /integrations/cloudflare/production-usage/ — geri dönüş, R2 arşivlemesi ve API korumasının birlikte bağlanmış hali.
• /integrations/cloudflare/security-and-operations/ — sabitleme, SSRF savunması ve gizli bilgi döndürme.