Unione

In breve

NextPDF\Pro\Merge\SmartMerger unisce più PDF in uno, poi applica le migliorie di Pro: un albero di segnalibri consolidato a partire dalle etichette di ciascun input, la deduplica delle pagine per content hash e la selezione degli intervalli di pagine per ciascun input. L’assemblaggio del documento di base passa attraverso il motore di unione a grafo di oggetti di Pro. Rinumera ogni input in un unico spazio di oggetti e scrive una tabella di riferimenti incrociati reale.

Disponibilità e licenze

Questa funzionalità è distribuita con 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.

Le classi di Merge sono disponibili ogni volta che il pacchetto Pro è installato. Nessun flag di capability a runtime controlla questo modulo.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

SmartMerger accetta un elenco di value object MergeInput. Ogni input porta con sé i byte del PDF di origine, un elenco facoltativo di intervalli di pagine e un’etichetta facoltativa. Gli input con intervalli di pagine sono ridotti alle pagine selezionate prima dell’unione. Il documento combinato è prodotto dal motore di unione a grafo di oggetti di Pro, che rinumera ogni input in un unico spazio di oggetti contiguo ed emette una tabella di riferimenti incrociati reale; il livello Pro aggiunge poi le migliorie richieste.

SmartMergeConfig controlla le migliorie:

• Il consolidamento dei segnalibri inserisce una voce di struttura per ciascun input etichettato, puntando all’inizio della sezione di quell’input. Segue il modello /Outlines del document catalog descritto in ISO 32000-2:2020 §7.7.2.
• La deduplica delle pagine rimuove le pagine duplicate byte-identiche tra gli input, confrontandole per content hash.
• La riscrittura dei collegamenti analizza l’output unito alla ricerca di azioni GoTo interne.

SmartMergeResult riporta i byte uniti più le statistiche: numero totale di pagine, conteggio delle sorgenti, dimensione dell’output, segnalibri aggiunti, duplicati rimossi, collegamenti rilevati e le etichette ordinate degli input.

Perché funziona così

Unire PDF non è concatenazione di byte: ogni input porta con sé i propri numeri di oggetto, la propria tabella di riferimenti incrociati e il proprio albero delle pagine, per cui un innesto ingenuo non si carica in nessun reader conforme. SmartMerger delega quindi l’assemblaggio di base al motore a grafo di oggetti di Pro (PdfSplitter::mergeDocuments()), che rinumera ogni input in un unico spazio di oggetti contiguo, ricostruisce un singolo albero delle pagine ed emette una tabella di riferimenti incrociati reale con veri offset di byte. Le migliorie di Pro — consolidamento dei segnalibri, deduplica e rilevamento dei collegamenti — si sovrappongono poi a quell’output verificato invece di reimplementare l’assemblaggio. La deduplica sull’intero documento e la gestione dei collegamenti solo in rilevamento sono confini di ambito deliberati che mantengono l’unione deterministica e sicura su input non attendibili.

Background di progettazione: L’anatomia di un file PDF.

Contratto di comportamento

• Input. Un elenco non vuoto di MergeInput. Un elenco vuoto solleva InvalidArgumentException. Il conteggio degli input e la dimensione in byte per ciascun input sono limitati da SmartMergeConfig (maxInputs, maxBytesPerInput).
• Output. Un SmartMergeResult. isValid() è true quando l’output inizia con l’header %PDF.
• Il consolidamento dei segnalibri aggiunge una voce per ciascun input che ha un’etichetta non vuota, quando consolidateBookmarks è abilitato.
• La deduplica è opt-in (deduplicatePages, disattivata per impostazione predefinita) e fa corrispondere pagine intere per content hash, non pagine visivamente simili.
• La riscrittura dei collegamenti nella release attuale rileva e conta le azioni GoTo interne; non esegue una ri-risoluzione completa delle destinazioni tra documenti. Trattare linksRewritten come un conteggio di rilevamento.
• Determinismo. Per input e configurazione identici lo stream di byte unito è stabile, fatto salvo il profilo di determinismo documentato del motore di unione di Pro.

Superficie API pubblica

Tipo	Genere	Membri chiave
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

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

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

Casi limite e insidie

• Un singolo input è valido e si unisce in una copia normalizzata di quel documento.
• La deduplica confronta il contenuto in byte di pagine intere; pagine che differiscono soltanto per metadati o numerazione degli oggetti non sono trattate come duplicati.
• La selezione degli intervalli di pagine su un input è applicata prima dell’ordinamento dell’unione.
• linksRewritten è un conteggio di azioni rilevate, non una garanzia che ogni destinazione di collegamento tra documenti sia stata ri-puntata.

Prestazioni

Il costo è dominato dal motore di unione di Pro e scala con il numero totale di byte in input e con il numero di pagine. La deduplica aggiunge un content hash per pagina. Il performance_budget nel front matter è il riferimento per ciascuna unione.

Note sulla sicurezza

Il conteggio degli input e la dimensione per ciascun input sono limitati da SmartMergeConfig per arginare l’esaurimento delle risorse da input ostili. L’unione non esegue gli script incorporati nei documenti. Vedere il modello di sicurezza di Core per il rafforzamento del parsing dello stream di byte.

Conformità

Asserzione	Clausola della specifica	Stato
Segnalibri consolidati tramite /Outlines	ISO 32000-2:2020 §7.7.2	Verificato (suite di unit test)
Deduplica delle pagine per content hash	—	Verificato (suite di unit test)
Ri-risoluzione completa dei collegamenti tra documenti	—	Non supportata (solo rilevamento)

Fallback / alternativa di Core

Per la concatenazione di base senza il consolidamento di Pro, il NextPDF\Document\PdfMerger open-source di Core è il percorso standalone supportato. SmartMerger non vi delega; l’unione di Pro gira sul proprio motore a grafo di oggetti. Vedere /modules/core/document/.

Nota sul confine Enterprise

Questo modulo esegue un’unione strutturale. Non esegue l’assemblaggio per legal-hold, l’oscuramento né il confezionamento della catena di custodia probatoria; queste funzioni non sono qui fornite.

Confine di pubblicazione

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

Vedere anche

• Merge — Riferimento approfondito
• Toc
• Diff
• Core document model