Merge — Riferimento approfondito

In breve

Questa pagina è il riferimento a livello di contratto per il modulo Merge di NextPDF Pro, NextPDF\Pro\Merge. SmartMerger assembla più documenti di input in uno solo e applica gli arricchimenti di Pro: un albero di segnalibri consolidato a partire dalle etichette dei singoli input, la deduplicazione dell’intero documento, la selezione di intervalli di pagine per singolo input e il rilevamento dei link interni. SemanticSplitter è il punto di ingresso complementare per la divisione in base alla struttura. Questa pagina definisce l’API pubblica, il contratto di comportamento osservabile, i limiti di risorse e le modalità di errore. La configurazione orientata alle attività e gli esempi si trovano nella pagina della funzionalità Merge.

Disponibilità e licenze

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Nessun flag di capacità a runtime applica un gate a questo modulo. Le classi Merge sono utilizzabili ogni volta che nextpdf/pro è installato e provvisto di licenza.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	Accetta e ignora il merger core legacy; uno splitter null costruisce lo splitter Pro predefinito	—	—	$coreMerger mantenuto solo per costruzione retrocompatibile
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	Riduce gli intervalli di pagine, deduplica gli interi input, delega l’assemblaggio di base, quindi inietta i segnalibri e conta i link in base alla configurazione	SmartMergeResult	InvalidArgumentException con un elenco di input vuoto; OverflowException quando il numero di input supera maxInputs o un input supera maxBytesPerInput	Unico punto di ingresso per l’unione
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	Value object; un $pageRanges vuoto seleziona tutte le pagine	—	—	Readonly
MergeInput::hasPageRanges()	—	True quando l’input contiene almeno un intervallo di pagine	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	Value object che contiene gli interruttori di arricchimento e i limiti di risorse	—	—	Readonly; la deduplicazione è opt-in
SmartMergeConfig::default()	—	Segnalibri e scansione dei link attivi, deduplicazione disattivata	self	—	Factory statica
SmartMergeConfig::basic()	—	Tutti gli arricchimenti disattivati; solo concatenazione di base	self	—	Factory statica
SmartMergeResult::__construct()	string $pdfData, int $totalPages, int $sourceCount, int $mergedSize, int $bookmarksAdded = 0, int $duplicatesRemoved = 0, int $linksRewritten = 0, list<string> $inputLabels = []	Contenitore readonly per i byte uniti e le statistiche di consolidamento	—	—	Readonly
SmartMergeResult::isValid()	—	True quando l’output inizia con l’header %PDF	bool	—	Solo verifica dell’header
SmartMergeResult::hasOptimizations()	—	True quando è stato rimosso un duplicato o conteggiato un link	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	Un argomento null costruisce lo splitter Pro predefinito	—	—	Constructor injection per i test
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	Rileva gli operatori Tf di dimensione da titolo come inizi di sezione e divide a quei confini; se non viene rilevata alcuna struttura restituisce una singola sezione con l’intero documento	SplitResult	InvalidArgumentException quando il buffer è vuoto o privo dell’header %PDF; OverflowException quando l’input supera 100 MB	Ripiega sulla divisione per intervallo di pagine di Core

Firme dei punti di ingresso

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

Contratto di comportamento

Pipeline di unione

SmartMerger::merge() esegue una pipeline fissa, osservata dall’esterno come segue.

1. Un elenco di input vuoto genera InvalidArgumentException. Il numero di input è quindi limitato da maxInputs; un superamento genera OverflowException.
2. La dimensione di ciascun input viene verificata rispetto a maxBytesPerInput prima dell’uso. Quando l’input dichiara intervalli di pagine, viene prima ridotto alle pagine selezionate tramite lo splitter Pro, dopodiché contribuisce solo con quelle pagine.
3. Quando deduplicatePages è abilitato, l’intera stringa di byte di ciascun documento di input viene sottoposta a fingerprint con la funzione non crittografica xxh128. Un input i cui byte corrispondono esattamente a un input precedente viene scartato. La deduplicazione avviene sull’intero documento ed è byte-esatta.
4. L’assemblaggio di base delega al motore Pro PdfSplitter::mergeDocuments(), che rinumera ogni input in un unico spazio di oggetti contiguo ed emette una vera tabella di cross-reference.
5. Il consolidamento dei segnalibri viene applicato quando consolidateBookmarks è abilitato e almeno un input contiene un’etichetta non vuota. Viene inserito un dizionario /Outlines minimale, collegato dal catalogo del documento, con una voce di outline per ogni input nell’ordine di unione.
6. Quando rewriteLinks è abilitato, l’output unito viene analizzato per individuare le azioni /S /GoTo e ne viene segnalato il conteggio.

Statistiche del risultato

SmartMergeResult riporta i byte uniti oltre alle statistiche. totalPages proviene dall’unione di base. sourceCount è il numero originale di input, rilevato prima della deduplicazione. mergedSize è la lunghezza in byte dell’output. bookmarksAdded conta solo gli input che hanno fornito un’etichetta non vuota. duplicatesRemoved conta gli interi input scartati. linksRewritten è il conteggio dei GoTo rilevati. inputLabels elenca le etichette risolte nell’ordine di unione. isValid() verifica l’header %PDF; hasOptimizations() è true quando è stato rimosso un duplicato o conteggiato un link.

Titoli dei segnalibri

Ogni voce di outline riporta l’etichetta dell’input come /Title, sottoposta a escape come stringa letterale PDF secondo ISO 32000-2:2020 §7.3.4.2. Il reverse solidus viene prima raddoppiato, le parentesi vengono sottoposte a escape, i byte di controllo denominati utilizzano le loro sequenze definite e qualsiasi byte non stampabile residuo diventa un escape ottale a tre cifre. Un’etichetta ostile non può quindi desincronizzare il delimitatore della stringa letterale né iniettare struttura di oggetti. Gli input con un’etichetta vuota ricevono un titolo segnaposto Document N, con indicizzazione a partire da uno.

Assemblaggio di base

Il metodo legacy Core PdfMerger::merge() è uno stub fail-closed deliberato in questa release; non viene mai invocato da SmartMerger. L’unione di base viene invece eseguita tramite Pro PdfSplitter::mergeDocuments(), così il file unito contiene una tabella di cross-reference byte-accurata con una voce per ogni oggetto indiretto secondo ISO 32000-2:2020 §7.5.4. Il determinismo segue il profilo documentato dello splitter Pro: input e configurazione identici producono un flusso di byte stabile.

Divisione in base alla struttura

SemanticSplitter::splitByStructure() analizza i content stream delle pagine alla ricerca di operatori set-font Tf pari o superiori a headingFontThreshold (predefinito 14.0) e tratta ogni pagina di questo tipo come l’inizio di una sezione. I confini vengono convertiti in intervalli di pagine e delegati a Pro PdfSplitter::split(). Quando non viene rilevato alcun confine, l’intero documento viene restituito come una singola sezione. L’input deve iniziare con %PDF e rimanere entro il limite di 100 MB.

Casi limite e modalità di errore

• Un elenco di input vuoto fallisce con InvalidArgumentException prima di qualsiasi assemblaggio.
• Un numero di input superiore a maxInputs (predefinito 100), o qualsiasi input superiore a maxBytesPerInput (predefinito 100 MB), fallisce con OverflowException. Entrambi i limiti sono rifiuti fail-closed deliberati, non errori transitori.
• La deduplicazione avviene sull’intero documento ed è byte-esatta. Due input che vengono visualizzati in modo identico ma differiscono anche di un solo byte vengono entrambi mantenuti, e duplicatesRemoved conta gli interi input scartati nonostante il nome orientato alle pagine deduplicatePages.
• sourceCount riflette il numero originale di input, non il numero di documenti dopo la deduplicazione.
• Il consolidamento dei segnalibri si attiva solo quando almeno un input ha un’etichetta non vuota. Con consolidateBookmarks a true ma tutte le etichette vuote, non viene scritto alcun oggetto /Outlines.
• Le voci di outline iniettate riportano i titoli e i link ad albero /Parent, /Prev, /Next; in questa release non incorporano destinazioni /Dest esplicite.
• La riscrittura dei link conta solo le azioni /S /GoTo; non ripunta le destinazioni tra gli oggetti rinumerati. Considerare linksRewritten come un conteggio di rilevamento.
• Il rilevamento di SemanticSplitter è lessicale. Si basa sugli operatori di dimensione font Tf, perciò le pagine solo immagine o con codifica insolita non producono confini e restituiscono una singola sezione con l’intero documento.

Comportamento in modalità FIPS

In questo modulo non avviene alcuna operazione crittografica, quindi non esiste alcun comportamento specifico della modalità FIPS. Il fingerprint di contenuto xxh128 utilizzato per la deduplicazione è un hash di rilevamento delle modifiche non crittografico e non ha alcun valore di integrità o probatorio.

Conformità

Dichiarazione	Standard	Clausola
Segnalibri consolidati scritti come dizionario /Outlines collegato dal catalogo del documento	ISO 32000-2:2020	§7.7.2
L’unione di base emette una tabella di cross-reference byte-accurata per ogni oggetto indiretto	ISO 32000-2:2020	§7.5.4
Titoli delle voci di outline sottoposti a escape come stringhe letterali PDF, con gestione di backslash e parentesi	ISO 32000-2:2020	§7.3.4.2
Ri-risoluzione completa dei link tra documenti	—	Non supportata (solo rilevamento GoTo)
Destinazioni di outline esplicite per sezione	—	Non emesse in questa release

Tutte le clausole sono parafrasate; NextPDF non riproduce il testo normativo. Si tratta di dichiarazioni di funzionalità, non di certificazioni; NextPDF non detiene alcuna certificazione e non ne concede alcuna.

Note di sviluppo

• Disponibilità nel pacchetto Pro: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult e SemanticSplitter dalla versione 2.2.0. Tutti sono attuali in nextpdf/pro 3.1.0.
• L’unione di base delega a Pro PdfSplitter::mergeDocuments(). Il metodo legacy Core PdfMerger::merge() è uno stub fail-closed in questa release e non viene mai chiamato.
• Abilitare deduplicatePages solo quando gli input possono essere interi documenti byte-identici; non riduce le copie quasi duplicate o ricodificate.
• Usare SmartMergeConfig::basic() per la pura concatenazione e ::default() per i segnalibri più la scansione dei link.
• Intercettare OverflowException quando si uniscono input non attendibili; i limiti di numero e dimensione sono rifiuti intenzionali.
• Preferire direttamente lo splitter Pro PdfSplitter per la semplice divisione per intervallo di pagine; ricorrere a SemanticSplitter solo quando è richiesta la suddivisione in sezioni guidata dai titoli.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi di supporto, le tabelle dei meccanismi, i nomi dei file dei runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Merge (funzionalità) — installazione, avvio rapido ed esempi di produzione.
• Toc — Riferimento approfondito
• Diff — Riferimento approfondito
• Document — Riferimento approfondito — splitter Pro e motore di unione di base.