Pro sürüm

Webview — Derinlemesine başvuru

Bir bakışta

Bu sayfa, genel NextPDF\Pro\Webview yüzeyini, bayt aralığı istek/yanıt modelini ve genel açılış sayfasının ötesindeki tam başarısızlık modlarını belgeler.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile teslim edilir ve Pro katmanlı bir lisans zarfıyla etkinleşir. Bu hakka sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Özellik başına bir lisans bayrağı yoktur; kod, Pro sürümüyle teslim edilir. PSR-17 ResponseFactoryInterface / StreamFactoryInterface ve gövde medya türü, lisanslama denetimleri değil, çalışma zamanı yapıcı parametreleridir.

Genel API yüzeyi

composer require nextpdf/pro

NextPDF\Pro\Webview altındaki genel türler:

LinearizedDocument — teslim için hazırlanmış, doğrulanmış bir linearized PDF.
ByteRangeResponder — RFC 9110 bayt aralığı HTTP yanıtlayıcısı.
ByteRange — bir temsil üzerinde bir karşılanabilir kapsayıcı bayt aralığı.
FirstPageProber — yapısal “tam indirmeden önce ilk sayfa” kanıtı.

NextPDF\Pro\Webview\Exception altındaki istisna türleri:

WebviewException (işaretçi arabirimi), UnsupportedDocumentException, RangeNotSatisfiableException.

`LinearizedDocument`

Özel bir yapıcısı olan final readonly bir sınıf; adlandırılmış yapıcı aracılığıyla örnekleyin.

static fromBytes(string $bytes): self — baytları Core’un okuma tarafı LinearizationView::fromPdf()’i aracılığıyla ayrıştırır. Belge linearized değilken, bildirilen /L gerçek bayt uzunluğuyla eşleşmediğinde veya /E ilk-sayfa-sonu kayması dosya içinde pozitif bir kayma olmadığında bir UnsupportedDocumentException oluşturur.
length(): int — belge uzunluğu, bayt cinsinden.
firstPagePrefixLength(): int — tam ilk sayfayı içeren minimal öncü önek: dosya uzunluğuna sıkıştırılmış /E kayması.
firstPageByteRange(): ByteRange — ilk sayfayı teslim eden kapsayıcı aralık [0, /E - 1]. Yalnızca önek boşsa bir RangeNotSatisfiableException oluşturur (derinlemesine savunma; fromBytes() zaten 0 < /E <= length’i garanti eder).
slice(int $firstByte, int $lastByte): string — kapsayıcı kaymalarla kesin programatik dilim; sınırların dışında olduğunda bir RangeNotSatisfiableException oluşturur.
etag(): string — baytlar için güçlü, deterministik SHA-256 varlık etiketi, yapımda bir kez belleğe alınmış.

Genel readonly özellikleri: bytes (ham PDF baytları) ve view (Core LinearizationView).

`ByteRangeResponder`

Yalnızca PSR-7 / PSR-17’ye karşı uygulanmış final readonly bir sınıf.

__construct(ResponseFactoryInterface $responses, StreamFactoryInterface $streams, string $contentType = 'application/pdf') — $contentType denetim karakterleri içerdiğinde bir InvalidArgumentException oluşturur (yanıt ve multipart parça başlıklarına araya eklenir; CR/LF ve diğer denetim baytları, başlık enjeksiyonunu önlemek için reddedilir).
respond(LinearizedDocument $document, ServerRequestInterface $request): ResponseInterface — belgenin kendi ETag’ini kullanarak bir linearized belge için bir aralık isteğini yanıtlar.
respondToBytes(string $bytes, ServerRequestInterface $request, ?string $etag = null): ResponseInterface — keyfi baytlar için (linearized olmadan aralıkları desteklemesi gereken bir temsil) bir aralık isteğini yanıtlar. null olduğunda ETag, baytlardan türetilir.
firstPageResponse(LinearizedDocument $document): ResponseInterface — tam olarak ilk sayfanın bayt aralığını taşıyan bir 206 oluşturur; “tam indirmeden önce ilk sayfa”nın sunucu-iletme biçimi.

`ByteRange`

Tek bir karşılanabilir kapsayıcı bayt aralığı için final readonly bir değer nesnesi (RFC 9110 §14.1.2).

__construct(int $firstByte, int $lastByte, int $contentLength) — 0 <= firstByte <= lastByte <= contentLength - 1 karşılanabilirliğini zorunlu kılar; aksi hâlde bir RangeNotSatisfiableException oluşturur.
length(): int — kapsayıcı açıklık (lastByte - firstByte + 1), her zaman >= 1.
contentRange(): string — RFC 9110 §14.4 Content-Range alan değeri bytes first-last/length.

Genel readonly özellikleri: firstByte, lastByte, contentLength.

`FirstPageProber`

Bir LinearizedDocument’tan oluşturulan final readonly bir sınıf.

prefixLength(): int — ilk sayfayı oluşturmak için gereken minimal öncü bayt sayısı.
prefixFraction(): float — önekin temsil ettiği, tüm dosyanın oranı (0.0–1.0); sıfır uzunluklu bir dosya için 1.0 döndürür.
hintStreamWithinPrefix(): bool — birincil ipucu akışı nesnesinin tamamen ilk-sayfa önekinin içinde olup olmadığı (böylece yalnızca önek, bir okuyucunun sayfa-1 nesnelerini bulmasına olanak tanır). İpucu akışının pozitif uzunluğa sahip olması gerekir.
isFirstPageSelfContained(): bool — birleşik yapısal kanıt: dosyaya sığan ve ipucu akışını tamamen içeren pozitif bir önek.

Bayt aralığı istek/yanıt modeli

ByteRangeResponder, RFC 9110 §14’ü izler. Uzunluğu ve güçlü bir SHA-256 ETag’i hesapladıktan sonra, Range ve If-Range başlıklarını okur ve karar verir:

Koşul	Durum	Notlar
Uygulanabilir `Range` yok veya `If-Range` geçerli güçlü `ETag` ile eşleşmiyor	`200 OK`	Tam gövde. `If-Range`’in yalnızca güçlü varlık etiketi biçimi onurlandırılır (RFC 9110 §13.1.5).
Tanınmayan aralık birimi veya söz dizimsel olarak geçersiz `Range`	`200 OK`	Başlık yok sayılır (RFC 9110 §14.2).
Bir karşılanabilir aralık	`206 Partial Content`	`Content-Range` taşır.
Birden çok karşılanabilir aralık	`206 Partial Content`	Türetilmiş bir sınırla `multipart/byteranges`.
Geçerli bayt aralıkları, hiçbiri karşılanamaz	`416 Range Not Satisfiable`	`Content-Range: bytes */length` taşır (RFC 9110 §15.3.7).

Her yanıt, Accept-Ranges: bytes ve güçlü ETag’i ilan eder. 200 ve 206 yanıtları ayrıca Content-Type ve Content-Length ayarlar.

Aralık ayrıştırma, yalnızca bytes= birimini kabul eder. Açık first-last, açık uçlu first- (sona sıkıştırılmış) ve sonek -N’yi (son N bayt; temsil kadar büyük bir sonek onun tamamını seçer) destekler. Çıplak bir - (veya başka türlü bozuk herhangi bir belirtim), tüm Range başlığını söz dizimsel olarak geçersiz kılar; böylece başlık yok sayılır ve tam 200 OK temsili döndürülür. Bir -0 soneki veya ilk kayması sondaki ya da sonun ötesinde olan herhangi bir belirtim, karşılanamaz bir belirtimdir ve düşürülür; başlıktaki hiçbir belirtim karşılanamazsa yanıt 416 Range Not Satisfiable’dır. Büyük ondalık kaymalar, tamsayı-taşma doygunluğuna güvenmeden karşılaştırılır; böylece 30 basamaklı bir Range değeri platformdan bağımsız olarak işlenir. Örtüşen karşılanabilir aralıklar, herhangi bir gövde oluşturulmadan önce birleştirilir; gerçekten farklı (örtüşmeyen) aralıklar, ayrı multipart parçaları olarak korunur.

Başarısızlık modları ve istisna modeli

WebviewException, Throwable’ı genişleten bir işaretçi arabirimidir; tüm alt sistemi tek tip olarak ele almak için onu yakalayın. Her iki somut istisna da onu uygular.

UnsupportedDocumentException (InvalidArgumentException’ı genişletir) — baytlar kullanılabilir bir linearized belge olmadığında LinearizedDocument::fromBytes() tarafından oluşturulur. Adlandırılmış yapıcılar: notLinearized() (hiçbir /Linearized parametre sözlüğü yok), lengthMismatch($declaredLength, $actualLength) (bildirilen /L gerçek uzunlukla eşleşmiyor — kesilmiş, /L’nin ötesine bir artımlı güncelleme aracılığıyla eklenmiş veya uygunsuz) ve malformedFirstPageOffset($firstPageEndOffset, $length) (/E kayması dosya içinde pozitif bir kayma değil).
RangeNotSatisfiableException (OutOfRangeException’ı genişletir) — programatik-dilim hatası; kapsayıcı bir aralık belgenin dışına düştüğünde ByteRange::__construct() ve LinearizedDocument::slice() / firstPageByteRange() tarafından oluşturulur. Adlandırılmış yapıcı: outOfBounds($firstByte, $lastByte, $length).

HTTP yanıtlayıcısı, istemci Range başlıkları için RangeNotSatisfiableException oluşturmaz — karşılanamaz bir HTTP aralığı, bir istisna değil, bir 416 yanıtıdır (RFC 9110 §15.3.7). Bu istisna, sınırların dışındaki bir isteğin bir çağıran hatası olduğu doğrudan programatik dilimleme için ayrılmıştır. Yapılandırılan contentType denetim karakterleri içerdiğinde ByteRangeResponder::__construct(), düz bir InvalidArgumentException (bir WebviewException değil) oluşturur.

Hizmet reddi sertleştirmesi

Yanıtlayıcı, istek başına onurlandırılan farklı birleştirilmiş aralık sayısını sınırlar (multipart aralık-yükseltme sınıfı, Apache HTTPD CVE-2011-3192). Bir istek, birleştirilmiş aralıkların üst sınırından daha fazlasını veya tüm temsilden daha fazla toplam bayt istediğinde, Range yok sayılır ve tam bir 200 döndürülür. Multipart sınırı, deterministik olarak türetilir ve gövdenin içinde oluşmayacağı garanti edilene kadar yeniden türetilir; böylece sınır çakışması dışlanırken yeniden üretilebilir çıktı korunur.

Uygunluk

Bayt aralığı davranışı, RFC 9110’u (HTTP Semantics) izler: §14 (aralık istekleri), §13.1.5 (If-Range), §14.4 (Content-Range) ve §15.3.7 (416). Linearized belge yerleşimi, ISO 32000-2 Annex F’nin Fast Web View modelidir. Modül, testleri tarafından doğrulanan davranışın ötesinde başka hiçbir harici kural tanımlayıcısı öne sürmez.

Uç durumlar ve FIPS modu davranışı

respondToBytes(), ilk-sayfa anlam bilgisine ihtiyaç olmadığında keyfi baytlar üzerinde aralıklara hizmet eder.
Bir If-Range HTTP-tarihi doğrulayıcısı, bir uyumsuzluk olarak değerlendirilir → tam 200 (istemci yalnızca yeniden getirir).
ETag, yalnızca güçlü bir önbellek doğrulayıcısı olarak kullanılan bir SHA-256 karmasıdır; bu modül hiçbir imzalama veya başka kriptografik işlem gerçekleştirmez ve hiçbir FIPS’e özgü davranış tanımlamaz.

Yayımlama sınırı

Bu sayfa, yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalışma kitabı dosya adları ve talep önekleri kapsam dışıdır.