Pro edycja

Webview — pełna dokumentacja referencyjna

W skrócie

Ta strona dokumentuje publiczną powierzchnię NextPDF\Pro\Webview, model żądania/odpowiedzi zakresów bajtów oraz dokładne tryby awarii wykraczające poza publiczną stronę docelową.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Nie ma flagi licencji na poziomie pojedynczej funkcji; kod jest dostarczany z edycją Pro. ResponseFactoryInterface / StreamFactoryInterface z PSR-17 oraz typ media ciała to parametry konstruktora czasu działania, a nie mechanizmy kontroli licencji.

Powierzchnia publicznego API

composer require nextpdf/pro

Typy publiczne w NextPDF\Pro\Webview:

LinearizedDocument — zwalidowany zlinearyzowany PDF przygotowany do dostarczenia.
ByteRangeResponder — responder HTTP zakresów bajtów zgodny z RFC 9110.
ByteRange — jeden spełnialny inkluzywny zakres bajtów nad reprezentacją.
FirstPageProber — strukturalny dowód „pierwsza strona przed pełnym pobraniem”.

Typy wyjątków w NextPDF\Pro\Webview\Exception:

WebviewException (interfejs znacznikowy), UnsupportedDocumentException, RangeNotSatisfiableException.

`LinearizedDocument`

Klasa final readonly z prywatnym konstruktorem; instancjonuj przez konstruktor nazwany.

static fromBytes(string $bytes): self — parsuje bajty przez odczytową LinearizationView::fromPdf() z Core. Zgłasza UnsupportedDocumentException, gdy dokument nie jest zlinearyzowany, gdy zadeklarowane /L nie pasuje do rzeczywistej długości bajtów lub gdy przesunięcie końca pierwszej strony /E nie jest dodatnim przesunięciem wewnątrz pliku.
length(): int — długość dokumentu w bajtach.
firstPagePrefixLength(): int — minimalny wiodący prefiks zawierający kompletną pierwszą stronę: przesunięcie /E, przycięte do długości pliku.
firstPageByteRange(): ByteRange — inkluzywny zakres [0, /E - 1], który dostarcza pierwszą stronę. Zgłasza RangeNotSatisfiableException tylko wtedy, gdy prefiks jest pusty (obrona w głąb; fromBytes() już gwarantuje 0 < /E <= length).
slice(int $firstByte, int $lastByte): string — ścisły programowy wycinek z przesunięciami inkluzywnymi; zgłasza RangeNotSatisfiableException, gdy poza zakresem.
etag(): string — silny, deterministyczny entity-tag SHA-256 dla bajtów, memoizowany raz przy konstrukcji.

Publiczne właściwości readonly: bytes (surowe bajty PDF) oraz view (LinearizationView z Core).

`ByteRangeResponder`

Klasa final readonly zaimplementowana wyłącznie względem PSR-7 / PSR-17.

__construct(ResponseFactoryInterface $responses, StreamFactoryInterface $streams, string $contentType = 'application/pdf') — zgłasza InvalidArgumentException, gdy $contentType zawiera znaki sterujące (jest interpolowany do nagłówków odpowiedzi oraz nagłówków części multipart; CR/LF i inne bajty sterujące są odrzucane, aby zapobiec wstrzyknięciu nagłówka).
respond(LinearizedDocument $document, ServerRequestInterface $request): ResponseInterface — odpowiada na żądanie zakresu dla zlinearyzowanego dokumentu, używając własnego ETag dokumentu.
respondToBytes(string $bytes, ServerRequestInterface $request, ?string $etag = null): ResponseInterface — odpowiada na żądanie zakresu dla dowolnych bajtów (reprezentacja, która powinna obsługiwać zakresy, nie będąc zlinearyzowaną). ETag jest wyprowadzany z bajtów, gdy null.
firstPageResponse(LinearizedDocument $document): ResponseInterface — buduje 206 niosące dokładnie zakres bajtów pierwszej strony; forma server-push „pierwsza strona przed pełnym pobraniem”.

`ByteRange`

Obiekt wartości final readonly dla pojedynczego spełnialnego inkluzywnego zakresu bajtów (RFC 9110 §14.1.2).

__construct(int $firstByte, int $lastByte, int $contentLength) — egzekwuje spełnialność 0 <= firstByte <= lastByte <= contentLength - 1; w przeciwnym razie zgłasza RangeNotSatisfiableException.
length(): int — inkluzywna rozpiętość (lastByte - firstByte + 1), zawsze >= 1.
contentRange(): string — wartość pola Content-Range zgodna z RFC 9110 §14.4 bytes first-last/length.

Publiczne właściwości readonly: firstByte, lastByte, contentLength.

`FirstPageProber`

Klasa final readonly konstruowana z LinearizedDocument.

prefixLength(): int — minimalna wiodąca liczba bajtów potrzebna do wyrenderowania pierwszej strony.
prefixFraction(): float — ułamek całego pliku (0.0–1.0), który reprezentuje prefiks; zwraca 1.0 dla pliku o zerowej długości.
hintStreamWithinPrefix(): bool — czy główny obiekt strumienia podpowiedzi leży w całości wewnątrz prefiksu pierwszej strony (więc sam prefiks pozwala czytnikowi zlokalizować obiekty strony 1). Strumień podpowiedzi musi mieć dodatnią długość.
isFirstPageSelfContained(): bool — łączny dowód strukturalny: dodatni prefiks, który mieści się w pliku i w całości zawiera strumień podpowiedzi.

Model żądania/odpowiedzi zakresów bajtów

ByteRangeResponder jest zgodny z RFC 9110 §14. Po obliczeniu długości oraz silnego ETag SHA-256 odczytuje nagłówki Range oraz If-Range i decyduje:

Warunek	Status	Uwagi
Brak stosowalnego `Range` lub `If-Range` nie pasuje do bieżącego silnego `ETag`	`200 OK`	Pełne ciało. Honorowana jest wyłącznie forma silnego entity-tag dla `If-Range` (RFC 9110 §13.1.5).
Nierozpoznana jednostka zakresu lub składniowo nieprawidłowy `Range`	`200 OK`	Nagłówek jest ignorowany (RFC 9110 §14.2).
Jeden spełnialny zakres	`206 Partial Content`	Niesie `Content-Range`.
Wiele spełnialnych zakresów	`206 Partial Content`	`multipart/byteranges` z wyprowadzoną granicą.
Prawidłowe zakresy bajtów, żaden niespełnialny	`416 Range Not Satisfiable`	Niesie `Content-Range: bytes */length` (RFC 9110 §15.3.7).

Każda odpowiedź ogłasza Accept-Ranges: bytes oraz silny ETag. Odpowiedzi 200 i 206 ustawiają również Content-Type oraz Content-Length.

Parsowanie zakresów akceptuje wyłącznie jednostkę bytes=. Obsługuje jawne first-last, otwarte first- (przycięte do końca) oraz sufiks -N (ostatnie N bajtów; sufiks co najmniej tak duży jak reprezentacja wybiera ją w całości). Samo - (lub każdy inaczej zniekształcony spec) czyni cały nagłówek Range składniowo nieprawidłowym, więc nagłówek jest ignorowany i zwracana jest pełna reprezentacja 200 OK. Sufiks -0 lub każdy spec, którego pierwsze przesunięcie jest na końcu lub poza nim, jest specem niespełnialnym i jest porzucany; jeśli żaden spec w nagłówku nie jest spełnialny, odpowiedzią jest 416 Range Not Satisfiable. Duże przesunięcia dziesiętne są porównywane bez polegania na nasyceniu wynikającym z przepełnienia liczb całkowitych, więc 30-cyfrowa wartość Range jest obsługiwana niezależnie od platformy. Nakładające się spełnialne zakresy są scalane, zanim zbuduje się jakiekolwiek ciało; naprawdę odrębne (nienakładające się) zakresy są zachowywane jako osobne części multipart.

Tryby awarii i model wyjątków

WebviewException to interfejs znacznikowy rozszerzający Throwable; przechwyć go, aby obsłużyć cały podsystem jednolicie. Oba konkretne wyjątki go implementują.

UnsupportedDocumentException (rozszerza InvalidArgumentException) — zgłaszany przez LinearizedDocument::fromBytes(), gdy bajty nie są użytecznym zlinearyzowanym dokumentem. Konstruktory nazwane: notLinearized() (brak słownika parametrów /Linearized), lengthMismatch($declaredLength, $actualLength) (zadeklarowane /L nie pasuje do rzeczywistej długości — obcięte, dopisane przez aktualizację przyrostową poza /L lub niezgodne) oraz malformedFirstPageOffset($firstPageEndOffset, $length) (przesunięcie /E nie jest dodatnim przesunięciem wewnątrz pliku).
RangeNotSatisfiableException (rozszerza OutOfRangeException) — błąd programowego wycinka, zgłaszany przez ByteRange::__construct() oraz LinearizedDocument::slice() / firstPageByteRange(), gdy zakres inkluzywny wykracza poza dokument. Konstruktor nazwany: outOfBounds($firstByte, $lastByte, $length).

Responder HTTP nie zgłasza RangeNotSatisfiableException dla klienckich nagłówków Range — niespełnialny zakres HTTP to odpowiedź 416 (RFC 9110 §15.3.7), a nie wyjątek. Ten wyjątek jest zarezerwowany dla bezpośredniego programowego wycinania, gdzie żądanie poza zakresem jest błędem wywołującego. ByteRangeResponder::__construct() zgłasza zwykły InvalidArgumentException (a nie WebviewException), gdy skonfigurowany contentType zawiera znaki sterujące.

Hartowanie przed atakami typu odmowa usługi

Responder ogranicza liczbę odrębnych scalonych zakresów honorowanych na żądanie (klasa multipart range-amplification, Apache HTTPD CVE-2011-3192). Gdy żądanie prosi o więcej scalonych zakresów niż limit, lub o więcej łącznych bajtów niż cała reprezentacja, Range jest ignorowany i zwracane jest pełne 200. Granica multipart jest wyprowadzana deterministycznie i wyprowadzana ponownie, dopóki z gwarancją nie wystąpi wewnątrz ciała, zachowując odtwarzalny wynik przy jednoczesnym wykluczeniu kolizji granicy.

Zgodność

Zachowanie zakresów bajtów jest zgodne z RFC 9110 (HTTP Semantics): §14 (żądania zakresów), §13.1.5 (If-Range), §14.4 (Content-Range) oraz §15.3.7 (416). Układ zlinearyzowanego dokumentu to model Fast Web View z ISO 32000-2 Annex F. Moduł nie deklaruje żadnych dalszych zewnętrznych identyfikatorów klauzul poza zachowaniem zweryfikowanym jego testami.

Przypadki brzegowe i zachowanie w trybie FIPS

respondToBytes() serwuje zakresy nad dowolnymi bajtami, gdy semantyka pierwszej strony nie jest potrzebna.
Walidator If-Range w postaci daty HTTP jest traktowany jako brak dopasowania → pełne 200 (klient po prostu pobiera ponownie).
ETag to skrót SHA-256 używany wyłącznie jako silny walidator pamięci podręcznej; ten moduł nie wykonuje podpisywania ani innych operacji kryptograficznych i nie definiuje zachowania specyficznego dla FIPS.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.