Pro Edition

Webview — Ausführliche Referenz

Auf einen Blick

Diese Seite dokumentiert die öffentliche NextPDF\Pro\Webview-Oberfläche, das Byte-Range-Request/Response-Modell und die exakten Fehlermodi über die öffentliche Landing-Page hinaus.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird in NextPDF Pro (nextpdf/pro) ausgeliefert und aktiviert sich mit einem Lizenz-Envelope der Pro-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz erwerben.

Es gibt kein per-Feature-Lizenz-Flag; der Code wird mit der Pro-Edition ausgeliefert. Das PSR-17-ResponseFactoryInterface / StreamFactoryInterface und der Body-Media-Type sind Laufzeit-Konstruktorparameter, keine Lizenzierungskontrollen.

Öffentliche API-Oberfläche

composer require nextpdf/pro

Öffentliche Typen unter NextPDF\Pro\Webview:

LinearizedDocument — ein validiertes linearisiertes PDF, für die Auslieferung vorbereitet.
ByteRangeResponder — der RFC-9110-Byte-Range-HTTP-Responder.
ByteRange — ein erfüllbares inklusives Byte-Range über eine Repräsentation.
FirstPageProber — der strukturelle Nachweis „erste Seite vor dem vollständigen Download“.

Ausnahmetypen unter NextPDF\Pro\Webview\Exception:

WebviewException (Marker-Interface), UnsupportedDocumentException, RangeNotSatisfiableException.

`LinearizedDocument`

Eine final readonly-Klasse mit einem privaten Konstruktor; instanziieren Sie über den benannten Konstruktor.

static fromBytes(string $bytes): self — parst die Bytes über die Lese-seitige LinearizationView::fromPdf() von Core. Löst eine UnsupportedDocumentException aus, wenn das Dokument nicht linearisiert ist, wenn die deklarierte /L nicht der tatsächlichen Byte-Länge entspricht oder wenn der /E-End-of-First-Page-Offset kein positiver Offset innerhalb der Datei ist.
length(): int — die Dokumentlänge in Bytes.
firstPagePrefixLength(): int — das minimale führende Präfix, das die vollständige erste Seite enthält: der /E-Offset, auf die Dateilänge geklemmt.
firstPageByteRange(): ByteRange — das inklusive Range [0, /E - 1], das die erste Seite ausliefert. Löst eine RangeNotSatisfiableException nur dann aus, wenn das Präfix leer ist (Defence-in-Depth; fromBytes() garantiert bereits 0 < /E <= length).
slice(int $firstByte, int $lastByte): string — strikter programmatischer Slice mit inklusiven Offsets; löst eine RangeNotSatisfiableException aus, wenn außerhalb der Grenzen.
etag(): string — der starke, deterministische SHA-256-Entity-Tag für die Bytes, einmalig bei der Konstruktion memoisiert.

Öffentliche readonly-Eigenschaften: bytes (die rohen PDF-Bytes) und view (die Core-LinearizationView).

`ByteRangeResponder`

Eine final readonly-Klasse, ausschließlich gegen PSR-7 / PSR-17 implementiert.

__construct(ResponseFactoryInterface $responses, StreamFactoryInterface $streams, string $contentType = 'application/pdf') — löst eine InvalidArgumentException aus, wenn $contentType Steuerzeichen enthält (er wird in Response- und Multipart-Part-Header interpoliert; CR/LF und andere Steuer-Bytes werden zurückgewiesen, um Header-Injection zu verhindern).
respond(LinearizedDocument $document, ServerRequestInterface $request): ResponseInterface — beantwortet eine Range-Anfrage für ein linearisiertes Dokument, unter Verwendung des eigenen ETag des Dokuments.
respondToBytes(string $bytes, ServerRequestInterface $request, ?string $etag = null): ResponseInterface — beantwortet eine Range-Anfrage für beliebige Bytes (eine Repräsentation, die Ranges unterstützen sollte, ohne linearisiert zu sein). Der ETag wird aus den Bytes abgeleitet, wenn null.
firstPageResponse(LinearizedDocument $document): ResponseInterface — baut ein 206, das genau das Byte-Range der ersten Seite trägt; die Server-Push-Form von „erste Seite vor dem vollständigen Download“.

`ByteRange`

Ein final readonly-Value-Object für ein einzelnes erfüllbares inklusives Byte-Range (RFC 9110 §14.1.2).

__construct(int $firstByte, int $lastByte, int $contentLength) — erzwingt die Erfüllbarkeit 0 <= firstByte <= lastByte <= contentLength - 1; löst andernfalls eine RangeNotSatisfiableException aus.
length(): int — die inklusive Spanne (lastByte - firstByte + 1), stets >= 1.
contentRange(): string — der RFC-9110-§14.4-Content-Range-Feldwert bytes first-last/length.

Öffentliche readonly-Eigenschaften: firstByte, lastByte, contentLength.

`FirstPageProber`

Eine final readonly-Klasse, konstruiert aus einem LinearizedDocument.

prefixLength(): int — minimale führende Byte-Anzahl, die zum Rendern der ersten Seite benötigt wird.
prefixFraction(): float — Anteil der gesamten Datei (0.0–1.0), den das Präfix darstellt; gibt 1.0 für eine Datei der Länge null zurück.
hintStreamWithinPrefix(): bool — ob das primäre Hint-Stream-Objekt vollständig innerhalb des First-Page-Präfixes liegt (sodass das Präfix allein einem Reader erlaubt, die Objekte von Seite 1 zu lokalisieren). Der Hint-Stream muss eine positive Länge haben.
isFirstPageSelfContained(): bool — der kombinierte strukturelle Nachweis: ein positives Präfix, das in die Datei passt und den Hint-Stream vollständig enthält.

Byte-Range-Request/Response-Modell

ByteRangeResponder folgt RFC 9110 §14. Nach der Berechnung der Länge und eines starken SHA-256-ETag liest er die Range- und If-Range-Header und entscheidet:

Bedingung	Status	Hinweise
Kein anwendbares `Range`, oder `If-Range` passt nicht zum aktuellen starken `ETag`	`200 OK`	Vollständiger Body. Nur die starke Entity-Tag-Form von `If-Range` wird honoriert (RFC 9110 §13.1.5).
Nicht erkannte Range-Unit oder syntaktisch ungültiges `Range`	`200 OK`	Der Header wird ignoriert (RFC 9110 §14.2).
Ein erfüllbares Range	`206 Partial Content`	Trägt `Content-Range`.
Mehrere erfüllbare Ranges	`206 Partial Content`	`multipart/byteranges` mit einer abgeleiteten Boundary.
Gültige Byte-Ranges, keines erfüllbar	`416 Range Not Satisfiable`	Trägt `Content-Range: bytes */length` (RFC 9110 §15.3.7).

Jede Antwort kündigt Accept-Ranges: bytes und den starken ETag an. 200- und 206-Antworten setzen außerdem Content-Type und Content-Length.

Das Range-Parsing akzeptiert nur die bytes=-Unit. Es unterstützt explizites first-last, offenes first- (auf das Ende geklemmt) und Suffix -N (die letzten N Bytes; ein Suffix, das mindestens so groß wie die Repräsentation ist, wählt sie vollständig aus). Ein nacktes - (oder eine anderweitig fehlerhafte Spec) macht den gesamten Range-Header syntaktisch ungültig, sodass der Header ignoriert und die vollständige 200 OK-Repräsentation zurückgegeben wird. Ein -0-Suffix oder jede Spec, deren erster Offset am oder jenseits des Endes liegt, ist eine unerfüllbare Spec und wird verworfen; wenn keine Spec im Header erfüllbar ist, ist die Antwort 416 Range Not Satisfiable. Große Dezimal-Offsets werden ohne Rückgriff auf Integer-Overflow-Sättigung verglichen, sodass ein 30-stelliger Range-Wert plattformunabhängig behandelt wird. Überlappende erfüllbare Ranges werden zusammengeführt, bevor irgendein Body gebaut wird; echt distinkte (nicht-überlappende) Ranges werden als separate Multipart-Parts bewahrt.

Fehlermodi & Ausnahmemodell

WebviewException ist ein Marker-Interface, das Throwable erweitert; fangen Sie es, um das gesamte Subsystem einheitlich zu behandeln. Beide konkreten Ausnahmen implementieren es.

UnsupportedDocumentException (erweitert InvalidArgumentException) — wird von LinearizedDocument::fromBytes() ausgelöst, wenn die Bytes kein verwendbares linearisiertes Dokument sind. Benannte Konstruktoren: notLinearized() (kein /Linearized-Parameter-Dictionary), lengthMismatch($declaredLength, $actualLength) (die deklarierte /L entspricht nicht der tatsächlichen Länge — gekürzt, über ein inkrementelles Update über /L hinaus angehängt oder nicht konform) und malformedFirstPageOffset($firstPageEndOffset, $length) (der /E-Offset ist kein positiver Offset innerhalb der Datei).
RangeNotSatisfiableException (erweitert OutOfRangeException) — der Programmatischer-Slice-Fehler, ausgelöst von ByteRange::__construct() und LinearizedDocument::slice() / firstPageByteRange(), wenn ein inklusives Range außerhalb des Dokuments fällt. Benannter Konstruktor: outOfBounds($firstByte, $lastByte, $length).

Der HTTP-Responder löst für Client-Range-Header keine RangeNotSatisfiableException aus — ein unerfüllbares HTTP-Range ist eine 416-Response (RFC 9110 §15.3.7), keine Ausnahme. Diese Ausnahme ist für das direkte programmatische Slicing reserviert, wo eine außerhalb der Grenzen liegende Anfrage ein Aufruferfehler ist. ByteRangeResponder::__construct() löst eine schlichte InvalidArgumentException (keine WebviewException) aus, wenn der konfigurierte contentType Steuerzeichen enthält.

Denial-of-Service-Härtung

Der Responder deckelt die Anzahl der distinkten zusammengeführten Ranges, die pro Anfrage honoriert werden (die Multipart-Range-Amplification-Klasse, Apache HTTPD CVE-2011-3192). Wenn eine Anfrage mehr als die Obergrenze zusammengeführter Ranges oder mehr Gesamt-Bytes als die gesamte Repräsentation verlangt, wird das Range ignoriert und ein vollständiges 200 zurückgegeben. Die Multipart-Boundary wird deterministisch abgeleitet und so lange neu abgeleitet, bis sie garantiert nicht innerhalb des Bodys auftritt, wodurch reproduzierbare Ausgabe bewahrt und eine Boundary-Kollision ausgeschlossen wird.

Konformität

Das Byte-Range-Verhalten folgt RFC 9110 (HTTP Semantics): §14 (Range-Anfragen), §13.1.5 (If-Range), §14.4 (Content-Range) und §15.3.7 (416). Das linearisierte Dokument-Layout ist das Fast-Web-View-Modell von ISO 32000-2 Annex F. Das Modul behauptet keine weiteren externen Klausel-Identifikatoren über das durch seine Tests verifizierte Verhalten hinaus.

Sonderfälle & Verhalten im FIPS-Modus

respondToBytes() liefert Ranges über beliebige Bytes aus, wenn die First-Page-Semantik nicht benötigt wird.
Ein If-Range-HTTP-Date-Validator wird als Nicht-Treffer behandelt → vollständiges 200 (der Client ruft einfach erneut ab).
Der ETag ist ein SHA-256-Hash, der rein als starker Cache-Validator verwendet wird; dieses Modul führt keine Signierung oder andere kryptografische Operationen durch und definiert kein FIPS-spezifisches Verhalten.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Geltungsbereichs.