Pro Edition

Document — Ausführliche Referenz

Auf einen Blick

Das Document-Modul stellt drei Pro-Primitive für den Zusammenbau bereit: das Aufteilen nach Seitenbereichen, das Zusammenführen mehrerer Dokumente und den Aufbau des Collection-Dictionarys für PDF-Portfolios. PdfSplitter extrahiert Seitenbereiche in eigenständige, strukturell konforme PDFs und führt ganze Dokumente zu einer neu nummerierten Datei zusammen. PdfPortfolio erstellt das Collection-Dictionary, das eingebettete Dateien mit sortierbaren Schema-Spalten darstellt. Jeder Einstiegspunkt begrenzt die Eingabegröße und die Objektanzahl gegenüber feindlichen Eingaben.

Verfügbarkeit & Lizenzierung

Diese Funktion ist Teil von NextPDF Pro (nextpdf/pro) und wird mit einer Lizenzhülle der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Öffentliche API-Oberfläche

Alle Modultypen liegen im Namespace NextPDF\Pro\Document. PageRange und MergeResult sind Core-Value-Objects aus NextPDF\Document.

Symbol	Parameter	Standardverhalten	Rückgabe	Löst aus oder schlägt fehl mit	Hinweise
`PdfSplitter::split()`	`string $pdfData`, `list<PageRange> $ranges`, `int $maxBytes = 100_000_000`, `int $maxRanges = 1000`	Erstellt ein eigenständiges PDF-Segment pro Bereich	`SplitResult`	`InvalidArgumentException` bei fehlendem `%PDF`-Header; `OverflowException` bei der Größen-, Bereichsanzahl- oder Closure-Schranke	Schranken laufen vor jedem Parsing
`PdfSplitter::splitEvery()`	`string $pdfData`, `int $pagesPerSegment`	Leitet zusammenhängende N-Seiten-Bereiche ab; das letzte Segment kann kürzer sein	`SplitResult`	`InvalidArgumentException`, wenn `$pagesPerSegment < 1` oder der Header fehlt	Delegiert an `split()` mit Standard-Obergrenzen
`PdfSplitter::extractPages()`	`string $pdfData`, `PageRange $range`	Gibt einen Bereich als eigenständige PDF-Bytes zurück	`string`	`InvalidArgumentException` bei fehlendem Header; `OverflowException` bei der Closure-Schranke	Auf diesem Pfad keine Obergrenzen-Parameter
`PdfSplitter::mergeDocuments()`	`list<string> $pdfs`, `int $maxInputs = 100`, `int $maxBytesEach = 100_000_000`	Führt Eingaben der Reihe nach zu einer neu nummerierten PDF zusammen	`MergeResult`	`InvalidArgumentException` bei leerer Liste oder Nicht-PDF-Eingabe; `OverflowException` bei der Anzahl-, Pro-Eingabe-Größen- oder Closure-Schranke	Seit 3.1.0; die höchste Eingabeversion bestimmt den Ausgabe-Header
`SplitResult`	readonly `$segments`, `$ranges`, `$totalPages`	Trägt rohe Segment-Bytes plus Quell-Metadaten	—	—	`final readonly` Value-Object
`SplitResult::count()`	—	Zählt erzeugte Segmente	`int`	—	—
`SplitResult::segment()`	`int $index`	Gibt die Bytes eines Segments zurück	`string`	`OutOfRangeException` bei einem Index außerhalb des gültigen Bereichs	Nullbasierter Index
`PdfPortfolio::__construct()`	`string $viewMode = 'tile'`	Validiert den View-Modus bei der Konstruktion	—	`InvalidArgumentException` bei einem anderen Modus als `tile`, `detail`, `hidden`	—
`PdfPortfolio::addSchema()`	`PortfolioField $field`	Hängt eine Schema-Spalte an	`self`	—	Fluent
`PdfPortfolio::addEntry()`	`PortfolioEntry $entry`	Hängt einen Dateieintrag an	`self`	—	Fluent
`PdfPortfolio::getSchema()`	—	Gibt die gesammelten Schema-Felder zurück	`list<PortfolioField>`	—	—
`PdfPortfolio::getEntries()`	—	Gibt die gesammelten Dateieinträge zurück	`list<PortfolioEntry>`	—	—
`PdfPortfolio::count()`	—	Zählt Dateieinträge	`int`	—	—
`PdfPortfolio::generateCollectionDictionary()`	—	Gibt den Collection-Dictionary-String aus	`string`	—	Schema- und Sort-Blöcke erscheinen nur, wenn Felder vorhanden sind
`PortfolioEntry`	`$filename`, `$data`, `$description = ''`, `$mimeType = 'application/octet-stream'`, `$customFields = []`	Unveränderliches Dateieintrag-Value-Object	—	—	`size()` gibt die Byte-Länge der Daten zurück
`PortfolioField`	`$name`, `PortfolioFieldType $type`, `$displayName = ''`, `$order = 0`, `$visible = true`	Unveränderliches Schema-Spalten-Value-Object	—	—	`effectiveDisplayName()` fällt auf `$name` zurück
`PortfolioFieldType`	String-Enum: `Text`, `Date`, `Number`, `FileName`, `Description`, `Size`, `ModDate`, `CreationDate`	Bildet jeden Fall über `pdfSubtype()` auf ein PDF-`/Subtype` ab	`string` (`S`, `D`, `N`, `F`, `Desc`)	—	Datumsartige Fälle teilen den Subtype `D`; numerische Fälle teilen `N`

Signaturen der Einstiegspunkte:

public function split(string $pdfData, array $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000): SplitResult

public function mergeDocuments(
    array $pdfs,
    int $maxInputs = 100,
    int $maxBytesEach = 100_000_000,
): MergeResult

public function __construct(
    private readonly string $viewMode = 'tile',
)

public function generateCollectionDictionary(): string

Verhaltensvertrag

Aufteilen und Zusammenführen teilen sich eine Objektgraph-Pipeline:

Die Eingabe muss mit dem %PDF-Header beginnen. Größen- und Anzahl-Schranken laufen vor dem Parsing und lösen bei Überschreitung OverflowException aus.
Blattseiten werden durch Suche nach Seitenobjekt-Markern erkannt; Seitenbaum-Knoten werden bei der Zählung ausgeschlossen.
Der Parser indexiert jedes unkomprimierte indirekte Objekt mit einer stream-bewussten Terminator-Suche. Das erste Auftreten einer Objekt-ID gewinnt, sodass Overrides aus inkrementellen Updates nicht angewendet werden.
Vererbbare Seitenbaum-Attribute (/Resources, /MediaBox, /CropBox, /Rotate) werden durch Durchlaufen der /Parent-Kette auf jede extrahierte Seite materialisiert, sodass Segmente eigenständig sind.
Die transitive Closure der indirekten Referenzen jeder Seite wird gesammelt – ohne die /Parent-Rückkante – und in einen frischen, zusammenhängenden ID-Raum neu nummeriert.
Der Serializer gibt den Header, den Catalog, den Pages-Baum, die Seitenobjekte und die Closure-Objekte aus, danach eine Cross-Reference-Tabelle mit byte-genauen Offsets und ein startxref, das auf das Schlüsselwort xref zeigt.
mergeDocuments wiederholt die Pipeline pro Eingabe in einen gemeinsamen ID-Raum. Die höchste Eingabe-PDF-Version bestimmt den Ausgabe-Header. Es ist der konforme Ersatz für den deaktivierten Core-Merger, der fail-closed bleibt.
Die Ausgabe ist deterministisch. Es werden keine Zeitstempel oder zufälligen Bezeichner ausgegeben, sodass identische Eingabe identische Bytes ergibt.

Portfolio-Zusammenbau:

Der Konstruktor validiert den View-Modus. Das ausgegebene /View-Token ist /T, /D bzw. /H für tile, detail und hidden.
generateCollectionDictionary() gibt /Type /Collection, das /View-Token, einen /Schema-Block, wenn Felder vorhanden sind, und eine /Sort-Direktive auf das erste Schema-Feld (aufsteigend) aus.
Jedes Schema-Feld gibt /Subtype (aus pdfSubtype()), /N (escapter Anzeigename), /O (Reihenfolge) und /V (Sichtbarkeit) aus.
Feldnamen werden zu gültigen PDF-Name-Tokens bereinigt; Nicht-Wort-Zeichen werden zu Unterstrichen. String-Werte werden als PDF-Literal-Strings escapt.
Dateieinträge werden über getEntries() zur Einbettung durch die Schreibschicht bereitgestellt. Das Collection-Dictionary selbst trägt nur View, Schema und Sort.

Grenzfälle & Fehlermodi

Ein Bereich, der keine Seiten trifft, ergibt ein minimales Ein-Seiten-Segment (612 x 792 MediaBox), keinen Fehler.
Ein Dokument ohne erkennbare Seiten-Marker wird als eine Seite gezählt.
Seiten, die in Object-Streams gespeichert sind, werden nicht erkannt; nur unkomprimierte indirekte Objekte nehmen an der Extraktion teil.
Bei doppelten Objekt-IDs wird die Revision mit dem niedrigsten Offset verwendet; spätere Revisionen aus inkrementellen Updates werden ignoriert.
Die Referenz-Closure pro Segment ist auf 50,000 Objekte begrenzt; ein bösartig selbstreferenzieller oder Fan-out-Graph löst OverflowException aus.
Standard-Obergrenzen: 100 MB Eingabe, 1,000 Bereiche, 100 Merge-Eingaben. Alle sind pro Aufruf durch den Aufrufer einstellbar.
splitEvery() weist eine Segmentgröße unter 1 mit InvalidArgumentException zurück.
SplitResult::segment() weist einen Index außerhalb des gültigen Bereichs mit OutOfRangeException zurück.
Zwei Schema-Feldnamen, die sich nur in der Interpunktion unterscheiden, werden zum selben Dictionary-Schlüssel bereinigt; das spätere Feld überdeckt im ausgegebenen Schema stillschweigend das frühere.
Dieses Modul führt keine kryptografischen Operationen durch; der FIPS-Modus ändert sein Verhalten nicht.

Konformität

Die Segment- und Merge-Ausgabe folgt dem Seitenobjekt-Modell von ISO 32000-2; die Quelle annotiert die relevanten Klauseln. Extern überprüfbare Aussagen:

Trailer-Layout, startxref-Byte-Offset und der %%EOF-Terminator folgen ISO 32000-2:2020, §7.5.5 — Referenz ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845.
Die /View-Werte des Collection-Dictionarys (/T, /D, /H) folgen ISO 32000-2:2020, §12.3.5 — Referenz 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd.
Die Collection-Feld-Einträge /Subtype, /N, /O und /V folgen ISO 32000-2:2020, §12.3.5 (collection field dictionary) — Referenz 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a.

Diese Aussagen beschreiben implementierte Funktionalität, die durch die Tests des Moduls verifiziert ist. Die Unterstützung eines Konstrukts ist keine Konformitätsaussage, und Konformität ist keine Zertifizierung; NextPDF besitzt für dieses Modul keine Zertifizierung durch Dritte.

Entwicklungshinweise

Alle Modulklassen sind final; die Result- und Value-Object-Typen sind readonly. Die Splitter- und Portfolio-Typen stammen aus 1.9.0; mergeDocuments() wurde in 3.1.0 hinzugefügt.
PageRange und MergeResult sind Core-Typen, sodass Aufrufstellen editions-portabel bleiben.
Segment-Trailer tragen nur /Size und /Root; es wird kein /ID-Dateibezeichner und kein /Info-Dictionary ausgegeben.
Für inkrementelle Update- oder Signatur-Workflows übergeben Sie die Segment-Bytes an das Writer-Modul, anstatt sie an Ort und Stelle nachzubearbeiten.
Das Modul protokolliert keine Dokumentinhalte.

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.