Pro Edition

Dokument

Auf einen Blick

Das Document-Modul teilt ein PDF nach Seitenbereich in Segmente und stellt PDF-Portfolios (Collections) mit sortierbaren Schema-Spalten zusammen. Beide Operationen sind gegen feindliche Eingaben begrenzt.

Verfügbarkeit & Lizenzierung

Diese Funktion wird mit NextPDF Pro (nextpdf/pro) ausgeliefert und aktiviert sich mit einer Lizenz-Hülle der Pro-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Document ist Teil der Pro-Edition, ohne separates Lizenz-Flag pro Funktion. Editionen vergleichen und Lizenz erwerben.

Installation

composer require nextpdf/pro:^3

Der Code liegt im Namensraum NextPDF\Pro\Document.

Konzeptioneller Überblick

Zwei Fähigkeiten werden bereitgestellt:

PdfSplitter extrahiert Seitenbereiche in eigenständige PDF-Segmente. Er erkennt Seiten, indem er die rohe Eingabe nach Seitenobjekten durchsucht, und umschließt die ausgewählten Seiten mit einem minimalen Katalog und Seitenbaum. Er unterstützt bereichsbasiertes Aufteilen, Aufteilen in fester Größe (splitEvery) und Einzelbereichs-Extraktion (extractPages).
PdfPortfolio baut ein PDF-Collection-Dictionary, das Dateianhänge mit einem definierten Schema aggregiert. Es unterstützt die Ansichtsmodi Kachel, Detail und versteckt und gibt ein Dictionary aus, das zur Aufnahme in den Dokumentkatalog geeignet ist.

Warum es so funktioniert

Ein PDF aufzuteilen ist kein Byte-Schnitt. Ein Seitenobjekt verweist über indirekte Referenzen auf gemeinsam genutzte Ressourcen, Schriften und Inhaltsströme. Zudem erbt es /MediaBox und /Resources von seinen Vorfahren im Seitenbaum. Daher rekonstruiert der Splitter jedes Segment als eigenständigen Objektgraphen: Er durchläuft die transitive Referenzhülle der ausgewählten Seiten, materialisiert die geerbten Attribute, nummeriert in einen frischen ID-Raum um und schreibt eine Cross-Reference-Tabelle mit byte-genauen Offsets. Der Hüllen-Durchlauf ist begrenzt, denn ein feindlicher Fan-out-Graph könnte andernfalls unbegrenzte Arbeit in ein Segment ziehen. Das Ergebnis öffnet sich als gültiges eigenständiges PDF, nicht als Fragment mit baumelnden Referenzen.

Design-Hintergrund: Die Anatomie einer PDF-Datei.

Verhaltensvertrag

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) erzwingt eine Eingabegrößen-Grenze und eine Bereichsanzahl-Grenze und weist Eingaben ab, die nicht mit dem PDF-Header beginnen.
splitEvery($pdfData, $pagesPerSegment) weist eine Segmentgröße unter 1 ab; das letzte Segment kann weniger Seiten enthalten.
PdfPortfolio weist zur Konstruktionszeit jeden Ansichtsmodus außer Kachel, Detail oder versteckt ab.
addSchema() und addEntry() geben das Portfolio für fluentes Verketten zurück; generateCollectionDictionary() gibt den Collection-Dictionary-String zurück.
Schema-Feldnamen werden für die Verwendung als PDF-Namensobjekte bereinigt; String-Werte werden für PDF-Literal-Strings escaped.

Codebeispiel — Schnellstart

Das Folgende spiegelt die dokumentierte öffentliche API wider. Das Repository liefert für dieses Modul kein lauffähiges Beispiel mit.

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

Codebeispiel — Produktion

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

Randfälle & Fallstricke

Der Splitter rekonstruiert jedes Segment als frischen Objektgraphen mit einer echten, byte-genauen Cross-Reference-Tabelle; Segmente sind gültige eigenständige PDFs. Er nummeriert in einen neuen ID-Raum um, statt das Byte-Layout der Quelle zu erhalten, reichen Sie Segment-Bytes daher an das Writer-Modul für Workflows mit inkrementeller Aktualisierung oder Signierung weiter.
Ein Bereich, der auf keine Seiten zutrifft, liefert ein minimales einseitiges Segment statt eines Fehlers.
Die Portfolio-Sortierung verwendet standardmäßig das erste Schema-Feld, aufsteigend.

Performance

Aufteilen und Portfolio-Zusammenstellung sind linear in der Eingabegröße und der Eintragsanzahl. Die Standard-Eingabeobergrenze beträgt 100 MB und die Standard-Bereichsobergrenze 1000; beide sind durch den Aufrufer nach unten regulierbar. Messen Sie mit repräsentativen Dokumenten.

Sicherheitshinweise

Behandeln Sie die Eingabe als nicht vertrauenswürdig. Größen- und Anzahl-Schutzmaßnahmen begrenzen die Ressourcennutzung. Das Modul bereinigt Feldnamen und escapet String-Werte, bevor sie in das Ausgabe-Dictionary gelangen. Es protokolliert keinen Dokumentinhalt.

Konformität

Das Portfolio-Dictionary folgt dem PDF-Collections-Modell und der Splitter folgt dem von ISO 32000-2 definierten Seitenobjekt-Modell; die Quelle annotiert die relevanten Klauseln. Der RAG-Korpus war zur Erstellungszeit nicht verfügbar, daher behauptet diese Seite keine externen Klauselbezeichner und beschränkt Konformitätsaussagen auf das durch die Tests des Moduls verifizierte Verhalten.

Hinweis zur Enterprise-Abgrenzung

Enterprise ändert das Document-Verhalten nicht. Enterprise ergänzt Archiv- und Compliance-Funktionen höherer Stufe, die separat dokumentiert sind; sie sind für Aufteilen oder Portfolio-Zusammenstellung nicht erforderlich.

Core-Rückfalloption / Alternative

Ohne Pro nutzen Sie die grundlegenden Dokument-Primitive von NextPDF Core; seitenbereichsbasiertes Aufteilen und Portfolio-Zusammenstellung sind Pro-Ergänzungen. Siehe /modules/document/.

Veröffentlichungsgrenze

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