Merge — Diepe referentie

In het kort

Deze pagina is de referentie op contractniveau voor de NextPDF Pro Merge-module, NextPDF\Pro\Merge. SmartMerger voegt meerdere invoerdocumenten samen tot één document en past Pro-verbeteringen toe: een geconsolideerde bookmarkboom uit labels per invoer, deduplicatie van hele documenten, paginabereikselectie per invoer, en detectie van interne links. SemanticSplitter is het bijbehorende, structuurbewuste startpunt voor splitsen. Deze pagina beschrijft de publieke API, het contract voor waarneembaar gedrag, de resourcegrenzen en de faalmodi. Taakgerichte setup en voorbeelden staan op de Merge-capaciteitspagina.

Beschikbaarheid en licentie

Deze capaciteit wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een licentie-envelop op Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de capaciteit niet. Vergelijk edities en vraag een licentie aan.

Geen runtime-capaciteitsflag gate’t deze module. De Merge-klassen zijn bruikbaar zodra nextpdf/pro geïnstalleerd en gelicentieerd is.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	Accepteert en negeert de legacy core-merger; een null-splitter construeert de standaard Pro-splitter	—	—	$coreMerger alleen behouden voor achterwaarts compatibele constructie
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	Reduceert paginabereiken, dedupliceert hele invoeren, delegeert de basisassemblage en injecteert vervolgens bookmarks en telt links volgens de config	SmartMergeResult	InvalidArgumentException bij een lege invoerlijst; OverflowException wanneer het aantal invoeren maxInputs overschrijdt of een invoer maxBytesPerInput overschrijdt	Enige startpunt voor merge
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	Value object; een lege $pageRanges selecteert alle pagina’s	—	—	Readonly
MergeInput::hasPageRanges()	—	True wanneer de invoer minstens één paginabereik draagt	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	Value object dat de verbeteringsschakelaars en de resourcegrenzen bevat	—	—	Readonly; deduplicatie is opt-in
SmartMergeConfig::default()	—	Bookmarks en linkscan aan, deduplicatie uit	self	—	Statische factory
SmartMergeConfig::basic()	—	Alle verbeteringen uit; alleen basisconcatenatie	self	—	Statische factory
SmartMergeResult::__construct()	string $pdfData, int $totalPages, int $sourceCount, int $mergedSize, int $bookmarksAdded = 0, int $duplicatesRemoved = 0, int $linksRewritten = 0, list<string> $inputLabels = []	Readonly drager voor de samengevoegde bytes en consolidatiestatistieken	—	—	Readonly
SmartMergeResult::isValid()	—	True wanneer de output begint met de %PDF-header	bool	—	Alleen headercontrole
SmartMergeResult::hasOptimizations()	—	True wanneer een duplicaat is verwijderd of een link is geteld	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	Een null-argument construeert de standaard Pro-splitter	—	—	Constructor-injectie voor testen
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	Detecteert Tf-operators met kopgrootte als sectiestarten en splitst op die grenzen; bij geen gedetecteerde structuur wordt één sectie voor het hele document geretourneerd	SplitResult	InvalidArgumentException wanneer de buffer leeg is of de %PDF-header mist; OverflowException wanneer de invoer 100 MB overschrijdt	Valt terug op Core-paginabereiksplitsing

Signatures van startpunten

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

Gedragscontract

Merge-pijplijn

SmartMerger::merge() draait een vaste pijplijn, extern als volgt waargenomen.

1. Een lege invoerlijst wekt InvalidArgumentException op. Het aantal invoeren wordt vervolgens begrensd door maxInputs; een overschrijding wekt OverflowException op.
2. Elke invoer wordt op grootte gecontroleerd tegen maxBytesPerInput vóór gebruik. Wanneer de invoer paginabereiken opgeeft, wordt hij eerst via de Pro-splitter gereduceerd tot de geselecteerde pagina’s en draagt hij daarna alleen die pagina’s bij.
3. Wanneer deduplicatePages is ingeschakeld, wordt de volledige bytestring van elk invoerdocument gevingerprint met de niet-cryptografische xxh128-functie. Een invoer waarvan de bytes exact overeenkomen met een eerdere invoer wordt weggelaten. Deduplicatie werkt op heel-document en byte-exact.
4. De basisassemblage delegeert aan de Pro-engine PdfSplitter::mergeDocuments(), die elke invoer hernummert naar één aaneengesloten objectruimte en een echte cross-referencetabel uitvoert.
5. Bookmarkconsolidatie wordt toegepast wanneer consolidateBookmarks is ingeschakeld en minstens één invoer een niet-leeg label draagt. Een minimale /Outlines-dictionary wordt ingevoegd, gekoppeld vanuit de document-catalogus, met één outline-vermelding per invoer in mergevolgorde.
6. Wanneer rewriteLinks is ingeschakeld, wordt de samengevoegde output gescand op /S /GoTo-acties en wordt hun aantal gerapporteerd.

Resultaatstatistieken

SmartMergeResult rapporteert de samengevoegde bytes plus statistieken. totalPages komt uit de basis-merge. sourceCount is het oorspronkelijke aantal invoeren, genomen vóór deduplicatie. mergedSize is de bytelengte van de output. bookmarksAdded telt alleen invoeren die een niet-leeg label aanleverden. duplicatesRemoved telt weggelaten hele invoeren. linksRewritten is het gedetecteerde GoTo-aantal. inputLabels somt de resolvde labels op in mergevolgorde. isValid() controleert de %PDF-header; hasOptimizations() is true wanneer een duplicaat is verwijderd of een link is geteld.

Bookmarktitels

Elke outline-vermelding draagt het invoerlabel als een /Title, ge-escaped als een PDF-literalstring volgens ISO 32000-2:2020 §7.3.4.2. De reverse solidus wordt eerst verdubbeld, haakjes worden ge-escaped, benoemde controlebytes gebruiken hun gedefinieerde sequenties, en elke resterende niet-afdrukbare byte wordt een octale escape van drie cijfers. Een vijandig label kan daardoor de literalstring-delimiter niet desynchroniseren of objectstructuur injecteren. Invoeren met een leeg label krijgen een Document N-placeholdertitel, geïndexeerd vanaf één.

Basisassemblage

De legacy Core-PdfMerger::merge() is in deze release een bewuste fail-closed stub; hij wordt nooit aangeroepen door SmartMerger. De basis-merge draait in plaats daarvan via Pro-PdfSplitter::mergeDocuments(), zodat het samengevoegde bestand een byte-accurate cross-referencetabel draagt met één vermelding per indirect object volgens ISO 32000-2:2020 §7.5.4. Determinisme volgt het gedocumenteerde profiel van de Pro-splitter: identieke invoeren en configuratie leveren een stabiele bytestroom op.

Structuurbewust splitsen

SemanticSplitter::splitByStructure() scant de contentstreams van pagina’s op Tf set-font-operators op of boven headingFontThreshold (standaard 14.0) en behandelt elke zo’n pagina als een sectiestart. Grenzen worden omgezet naar paginabereiken en gedelegeerd aan Pro-PdfSplitter::split(). Wanneer geen grens wordt gedetecteerd, wordt het hele document als één sectie geretourneerd. De invoer moet met %PDF beginnen en binnen de grens van 100 MB blijven.

Randgevallen en faalmodi

• Een lege invoerlijst faalt met InvalidArgumentException vóór enige assemblage.
• Een aantal invoeren boven maxInputs (standaard 100), of een invoer boven maxBytesPerInput (standaard 100 MB), faalt met OverflowException. Beide grenzen zijn bewuste fail-closed afwijzingen, geen tijdelijke fouten.
• Deduplicatie werkt op heel-document en byte-exact. Twee invoeren die identiek renderen maar in enige byte verschillen worden beide behouden, en duplicatesRemoved telt weggelaten hele invoeren ondanks de pagina-georiënteerde naam deduplicatePages.
• sourceCount weerspiegelt het oorspronkelijke aantal invoeren, niet het aantal documenten na deduplicatie.
• Bookmarkconsolidatie treedt alleen op wanneer minstens één invoer een niet-leeg label heeft. Met consolidateBookmarks op true maar elk label leeg wordt geen /Outlines-object geschreven.
• Geïnjecteerde outline-vermeldingen dragen titels en de boomlinks /Parent, /Prev, /Next; ze bevatten in deze release geen expliciete /Dest-bestemmingen.
• Herschrijven van links telt alleen /S /GoTo-acties; het herwijst geen bestemmingen over hernummerde objecten heen. Behandel linksRewritten als een detectietelling.
• Detectie door SemanticSplitter is lexicaal. Hij richt zich op Tf fontgrootte-operators, dus pagina’s die alleen uit afbeeldingen bestaan of ongebruikelijk gecodeerd zijn leveren geen grenzen op en retourneren één sectie voor het hele document.

FIPS-modusgedrag

In deze module vindt geen cryptografische bewerking plaats, dus bestaat er geen FIPS-modusspecifiek gedrag. De xxh128-contentvingerafdruk die voor deduplicatie wordt gebruikt is een niet-cryptografische change-detection-hash en draagt geen integriteits- of bewijswaarde.

Conformiteit

Bewering	Standaard	Clausule
Geconsolideerde bookmarks geschreven als een /Outlines-dictionary gekoppeld vanuit de document-catalogus	ISO 32000-2:2020	§7.7.2
Basis-merge voert een byte-accurate cross-referencetabel uit voor elk indirect object	ISO 32000-2:2020	§7.5.4
Titels van outline-vermeldingen ge-escaped als PDF-literalstrings, met verwerking van backslash en haakjes	ISO 32000-2:2020	§7.3.4.2
Volledige cross-document link-herresolutie	—	Niet ondersteund (alleen GoTo-detectie)
Expliciete outline-bestemmingen per sectie	—	Niet uitgevoerd in deze release

Alle clausules zijn geparafraseerd; NextPDF reproduceert geen normatieve tekst. Dit zijn capaciteitsverklaringen, geen certificeringen; NextPDF houdt geen certificering en verleent er geen.

Ontwikkelnotities

• Beschikbaarheid binnen het Pro-pakket: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult en SemanticSplitter sinds 2.2.0. Alle zijn actueel in nextpdf/pro 3.1.0.
• De basis-merge delegeert aan Pro-PdfSplitter::mergeDocuments(). De legacy Core-PdfMerger::merge() is in deze release een fail-closed stub en wordt nooit aangeroepen.
• Schakel deduplicatePages alleen in wanneer invoeren byte-identieke hele documenten kunnen zijn; het collabeert geen bijna-duplicaat of her-gecodeerde kopieën.
• Gebruik SmartMergeConfig::basic() voor pure concatenatie en ::default() voor bookmarks plus de linkscan.
• Vang OverflowException op bij het samenvoegen van niet-vertrouwde invoer; de grenzen voor aantal en grootte zijn opzettelijke afwijzingen.
• Geef de voorkeur aan de Pro-PdfSplitter rechtstreeks voor eenvoudig paginabereiksplitsen; grijp alleen naar SemanticSplitter wanneer kopgestuurde sectionering vereist is.

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.

Zie ook

• Merge (capaciteit) — installatie, snelstart en productievoorbeelden.
• Toc — Diepe referentie
• Diff — Diepe referentie
• Document — Diepe referentie — Pro-splitter en basis-merge-engine.