Pro Edition

Zusammenführung

Auf einen Blick

NextPDF\Pro\Merge\SmartMerger führt mehrere PDFs zu einem zusammen und wendet anschließend Pro-Erweiterungen an: einen konsolidierten Lesezeichenbaum aus den Labels der einzelnen Eingaben, eine Content-Hash- Seiten-Deduplizierung und eine Seitenbereichsauswahl pro Eingabe. Die grundlegende Dokumentzusammenstellung läuft über die Pro-Objektgraph-Merge- Engine. Sie nummeriert jede Eingabe in einen einzigen Objektraum um und schreibt eine echte Querverweistabelle.

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.

Die Merge-Klassen sind verfügbar, sobald das Pro-Paket installiert ist. Kein Laufzeit-Capability-Flag schaltet dieses Modul frei.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

SmartMerger akzeptiert eine Liste von MergeInput-Value-Objects. Jede Eingabe trägt die Quell-PDF-Bytes, eine optionale Liste von Seitenbereichen und ein optionales Label. Eingaben mit Seitenbereichen werden vor dem Zusammenführen auf die ausgewählten Seiten reduziert. Das kombinierte Dokument wird von der Pro-Objektgraph-Merge-Engine erzeugt, die jede Eingabe in einen zusammenhängenden Objektraum umnummeriert und eine echte Querverweistabelle ausgibt; die Pro-Schicht ergänzt anschließend die angeforderten Erweiterungen.

SmartMergeConfig steuert die Erweiterungen:

Lesezeichen-Konsolidierung fügt pro beschrifteter Eingabe einen Gliederungseintrag ein, der auf den Beginn des Abschnitts dieser Eingabe zeigt. Dies folgt dem Dokumentkatalog-Modell /Outlines in ISO 32000-2:2020 §7.7.2.
Seiten-Deduplizierung entfernt byte-identische doppelte Seiten über Eingaben hinweg, verglichen per Content-Hash.
Link-Umschreibung sucht in der zusammengeführten Ausgabe nach internen GoTo-Aktionen.

SmartMergeResult meldet die zusammengeführten Bytes sowie Statistiken: Gesamtseiten, Quellenanzahl, Ausgabegröße, hinzugefügte Lesezeichen, entfernte Duplikate, erkannte Links und die geordneten Eingabe-Labels.

Warum es so funktioniert

Das Zusammenführen von PDFs ist keine Byte-Verkettung: Jede Eingabe trägt ihre eigenen Objektnummern, ihre eigene Querverweistabelle und ihren eigenen Seitenbaum, sodass ein naives Zusammenfügen in keinem konformen Reader lädt. SmartMerger delegiert die grundlegende Zusammenstellung daher an die Pro-Objektgraph-Engine (PdfSplitter::mergeDocuments()), die jede Eingabe in einen zusammenhängenden Objektraum umnummeriert, einen einzigen Seitenbaum neu aufbaut und eine echte Querverweistabelle mit tatsächlichen Byte-Offsets ausgibt. Die Pro-Erweiterungen — Lesezeichen-Konsolidierung, Deduplizierung und Link-Erkennung — setzen dann auf dieser verifizierten Ausgabe auf, anstatt die Zusammenstellung neu zu implementieren. Die dokumentweite Deduplizierung und die reine Erkennung von Links sind bewusste Geltungsbereichsgrenzen, die das Zusammenführen deterministisch und bei nicht vertrauenswürdigen Eingaben sicher halten.

Design-Hintergrund: Die Anatomie einer PDF-Datei.

Verhaltensvertrag

Eingabe. Eine nicht leere Liste von MergeInput. Eine leere Liste löst InvalidArgumentException aus. Die Eingabeanzahl und die Bytegröße pro Eingabe sind durch SmartMergeConfig begrenzt (maxInputs, maxBytesPerInput).
Ausgabe. Ein SmartMergeResult. isValid() ist true, wenn die Ausgabe mit dem %PDF-Header beginnt.
Lesezeichen-Konsolidierung fügt pro Eingabe mit nicht leerem Label einen Eintrag hinzu, wenn consolidateBookmarks aktiviert ist.
Deduplizierung ist opt-in (deduplicatePages, standardmäßig aus) und gleicht ganze Seiten per Content-Hash ab, nicht visuell ähnliche Seiten.
Link-Umschreibung im aktuellen Release erkennt und zählt interne GoTo-Aktionen; sie führt keine vollständige dokumentübergreifende Ziel-Neuauflösung durch. Behandeln Sie linksRewritten als Erkennungszahl.
Determinismus. Für identische Eingaben und Konfiguration ist der zusammengeführte Byte-Stream stabil, vorbehaltlich des dokumentierten Determinismusprofils der Pro-Merge-Engine.

Öffentliche API-Oberfläche

Typ	Art	Schlüsselmitglieder
`NextPDF\Pro\Merge\SmartMerger`	`final class`	`__construct(?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null)`, `merge(array $inputs, SmartMergeConfig $config = new SmartMergeConfig()): SmartMergeResult`
`NextPDF\Pro\Merge\MergeInput`	`final readonly class`	`__construct(string $pdfData, array $pageRanges = [], string $label = '')`, `hasPageRanges(): bool`
`NextPDF\Pro\Merge\SmartMergeConfig`	`final readonly class`	`__construct(bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000)`, `default()`, `basic()`
`NextPDF\Pro\Merge\SmartMergeResult`	`final readonly class`	`string $pdfData`, `int $totalPages`, `int $sourceCount`, `int $bookmarksAdded`, `int $duplicatesRemoved`, `int $linksRewritten`, `array $inputLabels`, `isValid(): bool`, `hasOptimizations(): bool`

Codebeispiel — Schnellstart

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMerger;

$result = (new SmartMerger())->merge([
    new MergeInput(file_get_contents('cover.pdf'), label: 'Cover'),
    new MergeInput(file_get_contents('body.pdf'),  label: 'Body'),
]);

echo $result->totalPages, " pages, ",
     $result->bookmarksAdded, " bookmarks\n";

Codebeispiel — Produktion

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMergeConfig;
use NextPDF\Pro\Merge\SmartMerger;

function assemblePacket(array $sections): string
{
    $inputs = [];
    foreach ($sections as $label => $bytes) {
        $inputs[] = new MergeInput($bytes, label: (string) $label);
    }

    $config = new SmartMergeConfig(
        consolidateBookmarks: true,
        deduplicatePages: true,
        rewriteLinks: false,
        maxInputs: 50,
    );

    $result = (new SmartMerger())->merge($inputs, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('merge produced invalid output');
    }

    return $result->pdfData;
}

Randfälle & Fallstricke

Eine einzelne Eingabe ist gültig und wird zu einer normalisierten Kopie dieses Dokuments zusammengeführt.
Die Deduplizierung vergleicht den Byte-Inhalt ganzer Seiten; Seiten, die sich nur durch Metadaten oder Objektnummerierung unterscheiden, werden nicht als Duplikate behandelt.
Die Seitenbereichsauswahl auf einer Eingabe wird vor der Merge-Reihenfolge angewendet.
linksRewritten ist eine Zahl erkannter Aktionen, keine Garantie, dass jedes dokumentübergreifende Linkziel neu ausgerichtet wurde.

Performance

Die Kosten werden von der Pro-Merge-Engine dominiert und skalieren mit den gesamten Eingabebytes und der Seitenanzahl. Die Deduplizierung fügt einen Content-Hash pro Seite hinzu. Das Front-Matter performance_budget ist die Referenz pro Zusammenführung.

Sicherheitshinweise

Die Eingabeanzahl und die Größe pro Eingabe sind durch SmartMergeConfig begrenzt, um eine Ressourcenerschöpfung durch feindliche Eingaben zu beschränken. Das Zusammenführen führt keine eingebetteten Dokumentskripte aus. Siehe das Core-Sicherheitsmodell zur Härtung des Byte-Stream-Parsings.

Konformität

Anspruch	Spezifikationsklausel	Status
Konsolidierte Lesezeichen über `/Outlines`	ISO 32000-2:2020 §7.7.2	Verifiziert (Unit-Suite)
Content-Hash-Seiten-Deduplizierung	—	Verifiziert (Unit-Suite)
Vollständige dokumentübergreifende Link-Neuauflösung	—	Nicht unterstützt (nur Erkennung)

Core-Fallback / Alternative

Für eine grundlegende Verkettung ohne Pro-Konsolidierung ist der Open-Source- Core-NextPDF\Document\PdfMerger der unterstützte eigenständige Pfad. SmartMerger delegiert nicht an ihn; das Pro-Zusammenführen läuft auf seiner eigenen Objektgraph-Engine. Siehe /modules/core/document/.

Hinweis zur Enterprise-Grenze

Dieses Modul führt ein strukturelles Zusammenführen durch. Es führt keine Legal-Hold-Zusammenstellung, keine Schwärzung und kein beweisrechtliches Chain-of-Custody-Packaging durch; diese werden hier nicht bereitgestellt.

Veröffentlichungsgrenze

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