Webview

Bir bakışta

Webview, bir linearized (Fast Web View) PDF’yi HTTP üzerinden sunar; böylece bir istemci, dosyanın geri kalanı hâlâ yoldayken küçük bir öncü önekten sayfa 1’i oluşturmaya başlayabilir. Ham baytları bir LinearizedDocument olarak sarar, Range isteklerini bir PSR-7 ByteRangeResponder aracılığıyla RFC 9110 kısmi içerik yanıtlarıyla yanıtlar ve ilk sayfanın önek içinde kendi kendine yeterli olduğunu (FirstPageProber aracılığıyla) kanıtlayabilir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde gelir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye 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.

Ayrı bir özellik başına lisans bayrağı yoktur. Yanıtlayıcı, çalışma zamanında kendi PSR-17 fabrikalarınıza bağlanır — bir ResponseFactoryInterface ve bir StreamFactoryInterface — ve medya türü, bir lisans anahtarı değil, bir yapıcı argümanı olarak varsayılan application/pdf’dir.

Yükleme

composer require nextpdf/pro

Kod, NextPDF\Pro\Webview ad alanı altında yer alır.

Kavramsal genel bakış

Bir linearized PDF, belgenin ilk sayfası — linearization parametre sözlüğü, birincil ipucu akışı ve sayfa 1’in nesneleri — /E kaymasında biten bir öncü bölümde duracak şekilde yerleştirilir. Webview, bu yerleşimi aşamalı teslime dönüştürür.

LinearizedDocument::fromBytes(), baytları Core’un okuma tarafı LinearizationView’i aracılığıyla ayrıştırır (Pro, linearization ayrıştırmayı asla yeniden uygulamaz) ve kullanılabilir bir linearized belge olmayan her şeyi reddeder: hiç linearized olmayan, gerçek bayt uzunluğuyla eşleşmeyen bildirilen bir /L uzunluğu veya dosyanın içinde pozitif bir kayma olmayan bir /E ilk-sayfa-sonu kayması. Bu nedenle yapım toplamdır — bir LinearizedDocument tuttuğunuz anda, açığa çıkardığı her kayma güvenilirdir.

ByteRangeResponder ardından bir HTTP isteğini yanıtlar. Yalnızca PSR-7 / PSR-17’ye karşı uygulanmıştır, hiçbir çerçeve bağlantısı yoktur. Her zaman Accept-Ranges: bytes ve güçlü, deterministik bir SHA-256 ETag ilan eder, istemcinin Range başlığını RFC 9110 §14 uyarınca ayrıştırır ve şunlardan birini döndürür: tam bir 200 OK, bir 206 Partial Content tek aralığı, birkaç aralık için bir 206 multipart/byteranges yanıtı veya bir 416 Range Not Satisfiable.

FirstPageProber, yapısal kanıt tarafıdır: ilk-sayfa önekini, bu önekin tüm dosyanın temsil ettiği kesri ve birincil ipucu akışının tamamen içinde olup olmadığını niceler — bir okuyucunun sayfa-1 nesnelerini yalnızca önekten bulmasına olanak tanıyan özellik.

Neden bu şekilde çalışır

Webview, linearization’ı asla kendisi yeniden ayrıştırmaz. Core’un okuma tarafı LinearizationView’ini ödünç alır; böylece teslim katmanı, ikinci, kayan bir kopya yerine denetlenmiş tek bir ayrıştırıcıyı devralır. Yapım kasıtlı olarak toplamdır. LinearizedDocument::fromBytes(), hatalı biçimlendirilmiş bir yerleşimi önden reddeder; böylece bir Range yanıtının güvendiği her kayma önce doğrulanmıştır. Yanıtlayıcı yalnızca PSR-7 ve PSR-17 konuşur; böylece aynı kod, herhangi bir HTTP yığınından bir linearized PDF sunar. Aşamalı aralık teslimini güvenilmez istemcilere yüksek hacimde açmayı güvenli kılan şey, bu disiplindir.

Tasarım arka planı: Yüksek hacimli belge üretimi.

Aşamalı bayt aralığı sunumu nasıl çalışır

1. Oluşturulan PDF baytlarından bir LinearizedDocument oluşturun. Geçersiz girdi, önden bir UnsupportedDocumentException oluşturur.
2. Belgeyi ve gelen PSR-7 ServerRequestInterface’i ByteRangeResponder::respond()’a verin. Yanıtlayıcı, Range (ve isteğe bağlı If-Range ön koşulu) okur ve doğru PSR-7 ResponseInterface’i üretir.
3. İstemci, önce öncü öneki ister (veya siz onu firstPageResponse() ile gönderirsiniz), sayfa 1’i oluşturur, ardından kullanıcı kaydırdıkça kalan aralıkları ister.

Bayt aralığı modeli, RFC 9110 §14.1.2 uyarınca kapsayıcı kaymalar kullanır: bir ByteRange, contentLength boyutunda bir temsil üzerinde firstByte–lastByte’tır ve Content-Range alanı bytes first-last/length’tir.

Davranış sözleşmesi

• LinearizedDocument::fromBytes() toplamdır: linearized olmayan bir belge, bir /L uyumsuzluğu veya pozitif olmayan / dosya dışı bir /E kaymasının her biri, güvensiz bir belge üretmek yerine bir UnsupportedDocumentException oluşturur.
• ETag, tam baytlar üzerinde güçlü bir SHA-256 varlık etiketidir ve yapımda bir kez belleğe alınır. Aynı oluşturma girdisi, aynı baytları ve dolayısıyla aynı ETag’i verir; böylece önbellekler ve If-Range öngörülebilir davranır.
• Uygulanabilir bir Range olmayan bir istek, tam gövdeyle 200 OK döndürür. Geçerli güçlü ETag ile eşleşmeyen bir If-Range, Range’in yok sayılmasına ve tam bir 200’ün döndürülmesine neden olur (RFC 9110 §13.1.5). If-Range’in yalnızca güçlü varlık etiketi biçimi onurlandırılır; bir HTTP-tarihli If-Range, bir uyumsuzluk olarak değerlendirilir.
• Tanınmayan bir aralık birimi veya söz dizimsel olarak geçersiz bir Range yok sayılır ve tam bir 200 döndürülür (RFC 9110 §14.2).
• Karşılanabilir bir aralık, Content-Range ile 206 Partial Content döndürür; birden çok karşılanabilir aralık, 206 multipart/byteranges döndürür. Hiçbiri karşılanamayan geçerli bayt aralıkları, Content-Range: bytes */length ile 416 döndürür (RFC 9110 §15.3.7).
• firstPageResponse(), tam olarak ilk sayfanın bayt aralığı [0, /E - 1]’i taşıyan bir 206 yayar — “tam indirmeden önce ilk sayfa”nın sunucu-iletme biçimi.

Kod örneği — Hızlı başlangıç

Aşağıdaki, belgelenmiş genel API’yi yansıtır. Depo, bu modül için çalıştırılabilir bir örnek sunmaz.

use NextPDF\Pro\Webview\LinearizedDocument;
use NextPDF\Pro\Webview\ByteRangeResponder;

$document  = LinearizedDocument::fromBytes($pdfBytes);
$responder = new ByteRangeResponder($responseFactory, $streamFactory);

$response = $responder->respond($document, $request);

Kod örneği — İlk sayfa iletme ve sondalama

use NextPDF\Pro\Webview\LinearizedDocument;
use NextPDF\Pro\Webview\ByteRangeResponder;
use NextPDF\Pro\Webview\FirstPageProber;
use NextPDF\Pro\Webview\Exception\UnsupportedDocumentException;

try {
    $document = LinearizedDocument::fromBytes($pdfBytes);
} catch (UnsupportedDocumentException $e) {
    // Not a usable linearized document — fall back to plain full delivery.
    // ...
    return;
}

$prober = new FirstPageProber($document);
if ($prober->isFirstPageSelfContained()) {
    // Push exactly the first page's bytes for an instant render.
    $response = (new ByteRangeResponder($responseFactory, $streamFactory))
        ->firstPageResponse($document);
}

Uç durumlar ve dikkat edilecekler

• Webview, gerçekten linearized bir PDF gerektirir. Oluşturulan belge linearized değilse, oluşturma zamanında linearization’ı etkinleştirin veya onu düz tam teslimle sunun — yalnızca aralık desteğine ihtiyacınız olduğunda, ilk-sayfa anlam bilgisine değil, respondToBytes() yine de keyfi (linearized olmayan) baytlar üzerinde aralıklara hizmet edebilir.
• Artımlı güncellemeler önemlidir: bildirilen /L’sinin ötesine eklenen bir belge, bir uzunluk uyumsuzluğu olarak reddedilir, çünkü bayt aralığı kaymaları artık güvenilir olmazdı.
• Yanıtlayıcı, istek başına onurlandırdığı farklı aralık sayısını sınırlar. Üst sınırdan daha fazla birleştirilmiş aralık veya tüm temsilden daha fazla toplam bayt isteyen bir isteğin Range’i yok sayılır ve ona tam bir 200 sunulur.

Performans

İlk-sayfa öneki, dosya uzunluğuna sıkıştırılmış /E ilk-sayfa-sonu kaymasıdır; böylece FirstPageProber::prefixFraction(), ilk getirmenin tüm dosyaya göre ne kadar küçük olduğunu bildirir — çok sayfalı bir belge için bu, Fast Web View’in tüm amacıdır. Yanıt oluşturma, bellek-içi bayt dizesini dilimler; maliyet, seçilen baytlarla orantılıdır. ETag, belge başına bir kez hesaplanır. Temsili belgelerle ölçün.

Güvenlik notları

Girdiyi güvenilmez olarak değerlendirin. LinearizedDocument::fromBytes(), herhangi bir kayma kullanılmadan önce linearization değişmezlerini doğrular. Yanıtlayıcı; başlık enjeksiyonunu önlemek için denetim karakterleri içeren bir contentType’ı reddeder, gövdenin içinde oluşmayacağı garanti edilen bir multipart sınırı türetir ve hizmet reddi saldırısının multipart aralık-yükseltme sınıfına karşı savunmak için örtüşen aralıkları birleştirir ve sayılarını ve toplam boyutlarını sınırlar (Apache HTTPD CVE-2011-3192). Bu modül hiçbir belge içeriğini günlüğe kaydetmez.

Uygunluk

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

Enterprise sınır notu

Enterprise, Webview davranışını değiştirmez. Enterprise, ayrı olarak belgelenen daha üst katman uyumluluk ve arşivleme özellikleri ekler; bunlar bir linearized PDF’yi bayt aralıkları üzerinden sunmak için gerekli değildir.

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ı, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Webview — Deep Reference
• Writer
• Output Pipeline
• Optimizer