Pro editie

Samenvoegen

In het kort

NextPDF\Pro\Merge\SmartMerger voegt meerdere PDF’s samen tot één en past vervolgens Pro-verbeteringen toe: een geconsolideerde bladwijzerboom uit per-invoerlabels, content-hash-paginadeduplicatie en per-invoer paginabereikselectie. Het samenstellen van het basisdocument verloopt via de Pro-object-graph-samenvoegengine. Die hernummert elke invoer in één objectruimte en schrijft een echte kruisverwijzingstabel.

Beschikbaarheid en licenties

Deze functie zit in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop van de Pro-tier. Een deployment zonder dat recht laadt de klassen van de functie niet. Vergelijk edities en vraag een licentie aan.

De Merge-klassen zijn beschikbaar zodra het Pro-pakket is geïnstalleerd. Geen runtime-capaciteitsvlag bewaakt deze module.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

SmartMerger accepteert een lijst van MergeInput-value-objecten. Elke invoer draagt de bron-PDF-bytes, een optionele lijst van paginabereiken en een optioneel label. Invoer met paginabereiken wordt vóór het samenvoegen gereduceerd tot de geselecteerde pagina’s. Het gecombineerde document wordt geproduceerd door de Pro-object-graph-samenvoegengine, die elke invoer hernummert in één aaneengesloten objectruimte en een echte kruisverwijzingstabel uitgeeft; de Pro-laag voegt daarna de gevraagde verbeteringen toe.

SmartMergeConfig regelt de verbeteringen:

Bladwijzerconsolidatie voegt één outline-vermelding per gelabelde invoer toe, die wijst naar het begin van de sectie van die invoer. Dit volgt het document-catalog-/Outlines-model in ISO 32000-2:2020 §7.7.2.
Paginadeduplicatie verwijdert byte-identieke dubbele pagina’s over invoeren heen, vergeleken op content-hash.
Link-herschrijving scant op interne GoTo-acties in de samengevoegde uitvoer.

SmartMergeResult rapporteert de samengevoegde bytes plus statistieken: totaal aantal pagina’s, bronaantal, uitvoergrootte, toegevoegde bladwijzers, verwijderde duplicaten, gedetecteerde links en de geordende invoerlabels.

Waarom het zo werkt

Het samenvoegen van PDF’s is geen byte-aaneenschakeling: elke invoer draagt zijn eigen objectnummers, kruisverwijzingstabel en paginaboom, dus een naïeve splice laadt in geen enkele conforme reader. Daarom delegeert SmartMerger het samenstellen van het basisdocument aan de Pro-object-graph-engine (PdfSplitter::mergeDocuments()), die elke invoer hernummert in één aaneengesloten objectruimte, één paginaboom herbouwt en een echte kruisverwijzingstabel met echte byte-offsets uitgeeft. De Pro-verbeteringen — bladwijzerconsolidatie, deduplicatie en linkdetectie — komen dan bovenop die geverifieerde uitvoer in plaats van het samenstellen opnieuw te implementeren. Deduplicatie op documentniveau en detectie-alleen linkverwerking zijn bewuste scope-grenzen die het samenvoegen deterministisch en veilig houden op onbetrouwbare invoer.

Ontwerpachtergrond: De anatomie van een PDF-bestand.

Gedragscontract

Invoer. Een niet-lege lijst van MergeInput. Een lege lijst werpt InvalidArgumentException. Invoeraantal en per-invoer bytegrootte worden begrensd door SmartMergeConfig (maxInputs, maxBytesPerInput).
Uitvoer. Een SmartMergeResult. isValid() is waar wanneer de uitvoer begint met de %PDF-header.
Bladwijzerconsolidatie voegt één vermelding toe per invoer die een niet-leeg label heeft, wanneer consolidateBookmarks is ingeschakeld.
Deduplicatie is opt-in (deduplicatePages, standaard uit) en matcht hele pagina’s op content-hash, niet visueel vergelijkbare pagina’s.
Link-herschrijving in de huidige release detecteert en telt interne GoTo-acties; het voert geen volledige cross-document-bestemmings- herresolutie uit. Behandel linksRewritten als een detectietelling.
Determinisme. Voor identieke invoer en configuratie is de samengevoegde bytestream stabiel, onderhevig aan het gedocumenteerde determinismeprofiel van de Pro-samenvoegengine.

Publiek API-oppervlak

Type	Soort	Belangrijke leden
`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`

Codevoorbeeld — Snelstart

<?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";

Codevoorbeeld — Productie

<?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;
}

Randgevallen en valkuilen

Een enkele invoer is geldig en wordt samengevoegd tot een genormaliseerde kopie van dat document.
Deduplicatie vergelijkt byte-inhoud van hele pagina’s; pagina’s die alleen verschillen in metadata of objectnummering worden niet als duplicaten behandeld.
Paginabereikselectie op een invoer wordt vóór de samenvoegordening toegepast.
linksRewritten is een gedetecteerde-actie-telling, geen garantie dat elk cross-document-linkdoel opnieuw is aangewezen.

Prestaties

De kosten worden gedomineerd door de Pro-samenvoegengine en schalen met de totale invoerbytes en de paginatelling. Deduplicatie voegt één content-hash per pagina toe. De performance_budget-front-matter is de per-merge-referentie.

Beveiligingsnotities

Invoeraantal en per-invoer grootte worden begrensd door SmartMergeConfig om resource-uitputting door vijandige invoer te beperken. Samenvoegen voert geen ingebedde documentscripts uit. Zie het Core-beveiligingsmodel voor de hardening van bytestream-parsing.

Conformiteit

Claim	Spec-clausule	Status
Geconsolideerde bladwijzers via `/Outlines`	ISO 32000-2:2020 §7.7.2	Geverifieerd (unit suite)
Content-hash-paginadeduplicatie	—	Geverifieerd (unit suite)
Volledige cross-document-link-herresolutie	—	Niet ondersteund (alleen detectie)

Core-fallback / alternatief

Voor basis-aaneenschakeling zonder Pro-consolidatie is de opensource-Core NextPDF\Document\PdfMerger het ondersteunde standalone-pad. SmartMerger delegeert er niet naartoe; het Pro-samenvoegen draait op zijn eigen object-graph-engine. Zie /modules/core/document/.

Enterprise-grensnotitie

Deze module voert structureel samenvoegen uit. Ze voert geen legal-hold- samenstelling, redactie of bewijsrechtelijke chain-of-custody-verpakking uit; die worden hier niet geleverd.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten scope.