Fusion

En bref

NextPDF\Pro\Merge\SmartMerger fusionne plusieurs PDF en un seul, puis applique des améliorations Pro : un arbre de signets consolidé à partir des libellés par entrée, une déduplication de pages par empreinte de contenu et une sélection de plages de pages par entrée. L’assemblage du document de base s’exécute via le moteur de fusion par graphe d’objets Pro. Il renumérote chaque entrée dans un espace d’objets unique et écrit une véritable table de références croisées.

Disponibilité et licence

Cette fonctionnalité est livrée dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la fonctionnalité. Comparer les éditions et obtenir une licence.

Les classes Merge sont disponibles dès que le paquet Pro est installé. Aucun indicateur de capacité à l’exécution ne restreint ce module.

Installer

composer require nextpdf/pro:^3

Vue d’ensemble conceptuelle

SmartMerger accepte une liste d’objets-valeurs MergeInput. Chaque entrée porte les octets du PDF source, une liste optionnelle de plages de pages et un libellé optionnel. Les entrées dotées de plages de pages sont réduites aux pages sélectionnées avant la fusion. Le document combiné est produit par le moteur de fusion par graphe d’objets Pro, qui renumérote chaque entrée dans un espace d’objets contigu unique et émet une véritable table de références croisées ; la couche Pro ajoute ensuite les améliorations demandées.

SmartMergeConfig contrôle les améliorations :

• La consolidation des signets insère une entrée de plan par entrée libellée, pointant vers le début de la section de cette entrée. Cela suit le modèle /Outlines du catalogue de document dans ISO 32000-2:2020 §7.7.2.
• La déduplication de pages supprime les pages dupliquées octet-à-octet entre les entrées, comparées par empreinte de contenu.
• La réécriture de liens recherche les actions GoTo internes dans la sortie fusionnée.

SmartMergeResult rapporte les octets fusionnés plus des statistiques : nombre total de pages, nombre de sources, taille de sortie, signets ajoutés, doublons supprimés, liens détectés et les libellés d’entrée ordonnés.

Pourquoi cela fonctionne ainsi

Fusionner des PDF n’est pas une concaténation d’octets : chaque entrée porte ses propres numéros d’objets, sa table de références croisées et son arbre de pages, si bien qu’un collage naïf ne se charge dans aucun lecteur conforme. SmartMerger délègue donc l’assemblage de base au moteur par graphe d’objets Pro (PdfSplitter::mergeDocuments()), qui renumérote chaque entrée dans un espace d’objets contigu unique, reconstruit un arbre de pages unique et émet une véritable table de références croisées avec de vrais décalages d’octets. Les améliorations Pro — consolidation des signets, déduplication et détection de liens — se superposent alors à cette sortie vérifiée plutôt que de réimplémenter l’assemblage. La déduplication à l’échelle du document entier et la gestion des liens en détection seule sont des frontières de portée délibérées qui maintiennent la fusion déterministe et sûre sur des entrées non fiables.

Contexte de conception : L’anatomie d’un fichier PDF.

Contrat de comportement

• Entrée. Une liste non vide de MergeInput. Une liste vide lève InvalidArgumentException. Le nombre d’entrées et la taille en octets par entrée sont bornés par SmartMergeConfig (maxInputs, maxBytesPerInput).
• Sortie. Un SmartMergeResult. isValid() est vrai lorsque la sortie commence par l’en-tête %PDF.
• La consolidation des signets ajoute une entrée par entrée dotée d’un libellé non vide, lorsque consolidateBookmarks est activé.
• La déduplication est facultative (deduplicatePages, désactivée par défaut) et apparie des pages entières par empreinte de contenu, et non des pages visuellement similaires.
• La réécriture de liens dans la version actuelle détecte et compte les actions GoTo internes ; elle n’effectue pas de re-résolution complète des destinations entre documents. Traite linksRewritten comme un nombre de détections.
• Déterminisme. Pour des entrées et une configuration identiques, le flux d’octets fusionné est stable, sous réserve du profil de déterminisme documenté du moteur de fusion Pro.

Surface d’API publique

Type	Nature	Membres clés
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

Exemple de code — Démarrage rapide

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

Exemple de code — Production

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

Cas limites & pièges

• Une entrée unique est valide et se fusionne en une copie normalisée de ce document.
• La déduplication compare le contenu en octets des pages entières ; les pages qui ne diffèrent que par les métadonnées ou la numérotation des objets ne sont pas considérées comme des doublons.
• La sélection de plages de pages sur une entrée est appliquée avant l’ordre de fusion.
• linksRewritten est un nombre d’actions détectées, et non une garantie que chaque cible de lien entre documents a été re-pointée.

Performance

Le coût est dominé par le moteur de fusion Pro et évolue avec le total des octets d’entrée et le nombre de pages. La déduplication ajoute une empreinte de contenu par page. Le performance_budget du front matter est la référence par fusion.

Notes de sécurité

Le nombre d’entrées et la taille par entrée sont bornés par SmartMergeConfig pour limiter l’épuisement des ressources dû à des entrées hostiles. La fusion n’exécute pas les scripts incorporés dans le document. Voir le modèle de sécurité Core pour le durcissement de l’analyse du flux d’octets.

Conformité

Affirmation	Clause de spécification	Statut
Signets consolidés via /Outlines	ISO 32000-2:2020 §7.7.2	Vérifié (suite unitaire)
Déduplication de pages par empreinte de contenu	—	Vérifié (suite unitaire)
Re-résolution complète des liens entre documents	—	Non pris en charge (détection seulement)

Repli / alternative dans le Core

Pour une concaténation de base sans consolidation Pro, la classe Core open source NextPDF\Document\PdfMerger est le chemin autonome pris en charge. SmartMerger ne lui délègue pas ; la fusion Pro s’exécute sur son propre moteur par graphe d’objets. Voir /modules/core/document/.

Note sur la frontière Enterprise

Ce module effectue une fusion structurelle. Il n’effectue pas d’assemblage de mise sous séquestre légale, de caviardage ni d’empaquetage de chaîne de conservation probatoire ; ceux-ci ne sont pas fournis ici.

Frontière de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes auxiliaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors de portée.

Voir aussi

• Fusion — Référence détaillée
• Toc
• Diff
• Modèle de document Core