Merge — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Referenz auf Vertragsebene für das NextPDF Pro-Modul Merge, NextPDF\Pro\Merge. SmartMerger fügt mehrere Eingabedokumente zu einem zusammen und wendet Pro-Erweiterungen an: einen konsolidierten Lesezeichenbaum aus Beschriftungen pro Eingabe, eine dokumentweite Deduplizierung, die Auswahl von Seitenbereichen pro Eingabe sowie die Erkennung interner Verknüpfungen. SemanticSplitter ist der zugehörige strukturbewusste Einstiegspunkt für das Teilen. Diese Seite beschreibt die öffentliche API, den beobachtbaren Verhaltensvertrag, die Ressourcengrenzen und die Fehlermodi. Aufgabenorientierte Einrichtung und Beispiele finden Sie auf der Merge-Fähigkeitsseite.

Verfügbarkeit & Lizenzierung

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

Kein Laufzeit-Fähigkeitsflag steuert dieses Modul. Die Merge-Klassen sind nutzbar, sobald nextpdf/pro installiert und lizenziert ist.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	Nimmt den veralteten Core-Merger entgegen und ignoriert ihn; ein null-Splitter konstruiert den Standard-Pro-Splitter	—	—	$coreMerger nur zur abwärtskompatiblen Konstruktion beibehalten
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	Reduziert Seitenbereiche, dedupliziert ganze Eingaben, delegiert die Basiszusammenstellung, fügt dann Lesezeichen ein und zählt Verknüpfungen gemäß der Konfiguration	SmartMergeResult	InvalidArgumentException bei einer leeren Eingabeliste; OverflowException, wenn die Eingabeanzahl maxInputs überschreitet oder eine Eingabe maxBytesPerInput überschreitet	Einziger Einstiegspunkt für das Zusammenführen
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	Wertobjekt; ein leerer $pageRanges wählt alle Seiten aus	—	—	Readonly
MergeInput::hasPageRanges()	—	Wahr, wenn die Eingabe mindestens einen Seitenbereich trägt	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	Wertobjekt, das die Erweiterungsschalter und die Ressourcengrenzen hält	—	—	Readonly; Deduplizierung ist optional (opt-in)
SmartMergeConfig::default()	—	Lesezeichen und Verknüpfungsscan an, Deduplizierung aus	self	—	Statische Fabrik
SmartMergeConfig::basic()	—	Alle Erweiterungen aus; nur Basisverkettung	self	—	Statische Fabrik
SmartMergeResult::__construct()	string $pdfData, int $totalPages, int $sourceCount, int $mergedSize, int $bookmarksAdded = 0, int $duplicatesRemoved = 0, int $linksRewritten = 0, list<string> $inputLabels = []	Readonly-Träger für die zusammengeführten Bytes und die Konsolidierungsstatistik	—	—	Readonly
SmartMergeResult::isValid()	—	Wahr, wenn die Ausgabe mit dem %PDF-Header beginnt	bool	—	Nur Header-Prüfung
SmartMergeResult::hasOptimizations()	—	Wahr, wenn ein Duplikat entfernt oder eine Verknüpfung gezählt wurde	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	Ein null-Argument konstruiert den Standard-Pro-Splitter	—	—	Konstruktor-Injektion zum Testen
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	Erkennt überschriftsgroße Tf-Operatoren als Abschnittsanfänge und teilt an diesen Grenzen; ohne erkannte Struktur wird ein einziger dokumentweiter Abschnitt zurückgegeben	SplitResult	InvalidArgumentException, wenn der Puffer leer ist oder den %PDF-Header nicht enthält; OverflowException, wenn die Eingabe 100 MB überschreitet	Fällt auf den Core-Seitenbereichssplit zurück

Signaturen der Einstiegspunkte

public function __construct(
    ?PdfMerger $coreMerger = null,
    ?PdfSplitter $splitter = null,
)

public function merge(
    array $inputs,
    SmartMergeConfig $config = new SmartMergeConfig(),
): SmartMergeResult

public function __construct(
    public string $pdfData,
    public array $pageRanges = [],
    public string $label = '',
)

public function hasPageRanges(): bool

public function __construct(
    public bool $consolidateBookmarks = true,
    public bool $deduplicatePages = false,
    public bool $rewriteLinks = true,
    public int $maxInputs = 100,
    public int $maxBytesPerInput = 100_000_000,
)

public static function default(): self

public static function basic(): self

public function isValid(): bool

public function hasOptimizations(): bool

public function __construct(?PdfSplitter $splitter = null)

public function splitByStructure(
    string $pdfData,
    float $headingFontThreshold = 14.0,
): SplitResult

Verhaltensvertrag

Merge-Pipeline

SmartMerger::merge() führt eine feste Pipeline aus, die von außen wie folgt beobachtet wird.

1. Eine leere Eingabeliste löst InvalidArgumentException aus. Die Eingabeanzahl wird anschließend durch maxInputs begrenzt; eine Überschreitung löst OverflowException aus.
2. Jede Eingabe wird vor der Verwendung anhand von maxBytesPerInput auf ihre Größe geprüft. Wenn die Eingabe Seitenbereiche deklariert, wird sie zuerst über den Pro-Splitter auf die ausgewählten Seiten reduziert und trägt dann nur diese Seiten bei.
3. Wenn deduplicatePages aktiviert ist, wird die vollständige Byte-Zeichenkette jedes Eingabedokuments mit der nicht-kryptografischen Funktion xxh128 mit einem Fingerabdruck versehen. Eine Eingabe, deren Bytes exakt mit einer früheren Eingabe übereinstimmen, wird verworfen. Die Deduplizierung ist dokumentweit und bytegenau.
4. Die Basiszusammenstellung delegiert an die Pro-Engine PdfSplitter::mergeDocuments(), die jede Eingabe in einen zusammenhängenden Objektraum umnummeriert und eine echte Querverweistabelle ausgibt.
5. Die Lesezeichen-Konsolidierung wird angewendet, wenn consolidateBookmarks aktiviert ist und mindestens eine Eingabe eine nicht-leere Beschriftung trägt. Ein minimales /Outlines-Dictionary wird eingefügt, aus dem Dokumentkatalog verknüpft, mit einem Gliederungseintrag pro Eingabe in der Merge-Reihenfolge.
6. Wenn rewriteLinks aktiviert ist, wird die zusammengeführte Ausgabe auf /S /GoTo-Aktionen durchsucht und deren Anzahl wird gemeldet.

Ergebnisstatistik

SmartMergeResult meldet die zusammengeführten Bytes zuzüglich der Statistik. totalPages stammt aus dem Basis-Merge. sourceCount ist die ursprüngliche Eingabeanzahl, ermittelt vor der Deduplizierung. mergedSize ist die Byte-Länge der Ausgabe. bookmarksAdded zählt nur Eingaben, die eine nicht-leere Beschriftung lieferten. duplicatesRemoved zählt verworfene ganze Eingaben. linksRewritten ist die erkannte GoTo-Anzahl. inputLabels listet die aufgelösten Beschriftungen in der Merge-Reihenfolge auf. isValid() prüft den %PDF-Header; hasOptimizations() ist wahr, wenn ein Duplikat entfernt oder eine Verknüpfung gezählt wurde.

Lesezeichentitel

Jeder Gliederungseintrag trägt die Eingabebeschriftung als /Title, maskiert als PDF-Literalzeichenkette gemäß ISO 32000-2:2020 §7.3.4.2. Der umgekehrte Schrägstrich wird zuerst verdoppelt, Klammern werden maskiert, benannte Steuerbytes verwenden ihre definierten Sequenzen, und jedes verbleibende nicht-druckbare Byte wird zu einer dreistelligen oktalen Escape-Sequenz. Eine feindselige Beschriftung kann daher weder das Trennzeichen der Literalzeichenkette desynchronisieren noch Objektstruktur einschleusen. Eingaben mit einer leeren Beschriftung erhalten einen Platzhaltertitel Document N, eins-indexiert.

Basiszusammenstellung

Der veraltete Core PdfMerger::merge() ist in dieser Version ein bewusst fail-closed ausgelegter Stub; er wird von SmartMerger niemals aufgerufen. Der Basis-Merge läuft stattdessen über Pro PdfSplitter::mergeDocuments(), sodass die zusammengeführte Datei eine bytegenaue Querverweistabelle mit einem Eintrag pro indirektem Objekt gemäß ISO 32000-2:2020 §7.5.4 trägt. Die Determiniertheit folgt dem dokumentierten Profil des Pro-Splitters: identische Eingaben und Konfiguration ergeben einen stabilen Byte-Stream.

Strukturbewusstes Teilen

SemanticSplitter::splitByStructure() durchsucht die Inhaltsströme der Seiten nach Tf-Schriftsetz-Operatoren bei oder oberhalb von headingFontThreshold (Standard 14.0) und behandelt jede solche Seite als Abschnittsanfang. Grenzen werden in Seitenbereiche umgewandelt und an Pro PdfSplitter::split() delegiert. Wenn keine Grenze erkannt wird, wird das gesamte Dokument als ein einziger Abschnitt zurückgegeben. Die Eingabe muss mit %PDF beginnen und innerhalb der 100-MB-Grenze bleiben.

Randfälle & Fehlermodi

• Eine leere Eingabeliste scheitert mit InvalidArgumentException vor jeder Zusammenstellung.
• Eine Eingabeanzahl über maxInputs (Standard 100) oder eine Eingabe über maxBytesPerInput (Standard 100 MB) scheitert mit OverflowException. Beide Grenzen sind bewusste fail-closed Ablehnungen, keine transienten Fehler.
• Die Deduplizierung ist dokumentweit und bytegenau. Zwei Eingaben, die identisch gerendert werden, sich aber in irgendeinem Byte unterscheiden, werden beide beibehalten, und duplicatesRemoved zählt trotz des seitenorientierten Namens deduplicatePages verworfene ganze Eingaben.
• sourceCount spiegelt die ursprüngliche Eingabeanzahl wider, nicht die Dokumentanzahl nach der Deduplizierung.
• Die Lesezeichen-Konsolidierung wird nur ausgelöst, wenn mindestens eine Eingabe eine nicht-leere Beschriftung hat. Ist consolidateBookmarks wahr, aber jede Beschriftung leer, wird kein /Outlines-Objekt geschrieben.
• Eingefügte Gliederungseinträge tragen Titel sowie die Baumverknüpfungen /Parent, /Prev, /Next; sie betten in dieser Version keine expliziten /Dest-Ziele ein.
• Das Umschreiben von Verknüpfungen zählt nur /S /GoTo-Aktionen; es richtet Ziele nicht über umnummerierte Objekte hinweg neu aus. Behandeln Sie linksRewritten als eine Erkennungsanzahl.
• Die Erkennung von SemanticSplitter ist lexikalisch. Sie orientiert sich an Tf-Schriftgrößenoperatoren, sodass reine Bildseiten oder ungewöhnlich kodierte Seiten keine Grenzen erzeugen und einen einzigen dokumentweiten Abschnitt zurückgeben.

FIPS-Modus-Verhalten

In diesem Modul findet keine kryptografische Operation statt, daher existiert kein FIPS-modusspezifisches Verhalten. Der für die Deduplizierung verwendete xxh128-Inhaltsfingerabdruck ist ein nicht-kryptografischer Änderungserkennungs-Hash und trägt kein Integritäts- oder Beweisgewicht.

Konformität

Aussage	Standard	Klausel
Konsolidierte Lesezeichen als /Outlines-Dictionary geschrieben, verknüpft aus dem Dokumentkatalog	ISO 32000-2:2020	§7.7.2
Basis-Merge gibt eine bytegenaue Querverweistabelle für jedes indirekte Objekt aus	ISO 32000-2:2020	§7.5.4
Gliederungseintragstitel maskiert als PDF-Literalzeichenketten, mit Behandlung von Schrägstrich und Klammern	ISO 32000-2:2020	§7.3.4.2
Vollständige dokumentübergreifende Neuauflösung von Verknüpfungen	—	Nicht unterstützt (nur GoTo-Erkennung)
Explizite Gliederungsziele pro Abschnitt	—	In dieser Version nicht ausgegeben

Alle Klauseln sind paraphrasiert; NextPDF gibt keinen normativen Text wieder. Dies sind Fähigkeitsaussagen, keine Zertifizierungen; NextPDF hält keine Zertifizierung und erteilt keine.

Entwicklungshinweise

• Verfügbarkeit innerhalb des Pro-Pakets: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult und SemanticSplitter seit 2.2.0. Alle sind in nextpdf/pro 3.1.0 aktuell.
• Der Basis-Merge delegiert an Pro PdfSplitter::mergeDocuments(). Der veraltete Core PdfMerger::merge() ist in dieser Version ein fail-closed Stub und wird niemals aufgerufen.
• Aktivieren Sie deduplicatePages nur, wenn Eingaben bytegleiche ganze Dokumente sein können; es fasst keine nahezu doppelten oder neu kodierten Kopien zusammen.
• Verwenden Sie SmartMergeConfig::basic() für reine Verkettung und ::default() für Lesezeichen plus den Verknüpfungsscan.
• Fangen Sie OverflowException ab, wenn Sie nicht vertrauenswürdige Eingaben zusammenführen; die Anzahl- und Größengrenzen sind absichtliche Ablehnungen.
• Bevorzugen Sie den Pro PdfSplitter direkt für einfaches Teilen nach Seitenbereichen; greifen Sie nur dann zu SemanticSplitter, wenn eine überschriftsgesteuerte Abschnittsbildung erforderlich ist.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich das von außen beobachtbare Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe sind nicht Gegenstand dieser Seite.

Siehe auch

• Merge (Fähigkeit) — Installation, Schnellstart und Produktionsbeispiele.
• Toc — Ausführliche Referenz
• Diff — Ausführliche Referenz
• Document — Ausführliche Referenz — Pro-Splitter und Basis-Merge-Engine.