Combinación

De un vistazo

NextPDF\Pro\Merge\SmartMerger combina varios PDF en uno y luego aplica mejoras de Pro: un árbol de marcadores consolidado a partir de las etiquetas por entrada, deduplicación de páginas por hash de contenido y selección de intervalos de páginas por entrada. El ensamblaje del documento base se ejecuta a través del motor de combinación de grafo de objetos de Pro. Renumera cada entrada en un único espacio de objetos y escribe una tabla de referencias cruzadas real.

Disponibilidad y licencia

Esta capacidad se distribuye con NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa habilitación no carga las clases de la capacidad. Compara ediciones y obtén una licencia.

Las clases de Merge están disponibles siempre que el paquete Pro esté instalado. Ningún indicador de capacidad en tiempo de ejecución restringe este módulo.

Instalación

composer require nextpdf/pro:^3

Panorama conceptual

SmartMerger acepta una lista de objetos de valor MergeInput. Cada entrada lleva los bytes del PDF de origen, una lista opcional de intervalos de páginas y una etiqueta opcional. Las entradas con intervalos de páginas se reducen a las páginas seleccionadas antes de combinar. El documento combinado lo produce el motor de combinación de grafo de objetos de Pro, que renumera cada entrada en un único espacio de objetos contiguo y emite una tabla de referencias cruzadas real; la capa de Pro añade luego las mejoras solicitadas.

SmartMergeConfig controla las mejoras:

• La consolidación de marcadores inserta una entrada de esquema por cada entrada etiquetada, que apunta al inicio de la sección de esa entrada. Esto sigue el modelo /Outlines del catálogo de documento de ISO 32000-2:2020 §7.7.2.
• La deduplicación de páginas elimina las páginas duplicadas idénticas a nivel de bytes entre entradas, comparadas por hash de contenido.
• La reescritura de enlaces busca acciones GoTo internas en la salida combinada.

SmartMergeResult informa de los bytes combinados más estadísticas: total de páginas, recuento de fuentes, tamaño de salida, marcadores añadidos, duplicados eliminados, enlaces detectados y las etiquetas de entrada ordenadas.

Por qué funciona así

Combinar PDF no es una concatenación de bytes: cada entrada lleva sus propios números de objeto, tabla de referencias cruzadas y árbol de páginas, de modo que un empalme ingenuo no carga en ningún lector conforme. Por eso SmartMerger delega el ensamblaje base al motor de grafo de objetos de Pro (PdfSplitter::mergeDocuments()), que renumera cada entrada en un único espacio de objetos contiguo, reconstruye un único árbol de páginas y emite una tabla de referencias cruzadas real con desplazamientos de bytes verdaderos. Las mejoras de Pro —consolidación de marcadores, deduplicación y detección de enlaces— se superponen luego sobre esa salida verificada en lugar de reimplementar el ensamblaje. La deduplicación de documento completo y el tratamiento de enlaces solo de detección son límites de alcance deliberados que mantienen la combinación determinista y segura ante entradas no confiables.

Contexto de diseño: La anatomía de un archivo PDF.

Contrato de comportamiento

• Entrada. Una lista no vacía de MergeInput. Una lista vacía genera InvalidArgumentException. El recuento de entradas y el tamaño en bytes por entrada están acotados por SmartMergeConfig (maxInputs, maxBytesPerInput).
• Salida. Un SmartMergeResult. isValid() es verdadero cuando la salida comienza con la cabecera %PDF.
• La consolidación de marcadores añade una entrada por cada entrada que tiene una etiqueta no vacía, cuando consolidateBookmarks está habilitado.
• La deduplicación es opcional (deduplicatePages, desactivada por defecto) y compara páginas completas por hash de contenido, no páginas visualmente similares.
• La reescritura de enlaces en la versión actual detecta y cuenta acciones GoTo internas; no realiza una nueva resolución completa de destinos entre documentos. Trata linksRewritten como un recuento de detección.
• Determinismo. Para entradas y configuración idénticas, el flujo de bytes combinado es estable, sujeto al perfil de determinismo documentado del motor de combinación de Pro.

Superficie de API pública

Tipo	Clase	Miembros clave
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

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

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

Casos límite y trampas

• Una sola entrada es válida y se combina en una copia normalizada de ese documento.
• La deduplicación compara el contenido de bytes de página completa; las páginas que difieren solo por los metadatos o la numeración de objetos no se tratan como duplicados.
• La selección de intervalos de páginas en una entrada se aplica antes del ordenamiento de la combinación.
• linksRewritten es un recuento de acciones detectadas, no una garantía de que cada destino de enlace entre documentos se haya reapuntado.

Rendimiento

El coste está dominado por el motor de combinación de Pro y escala con el total de bytes de entrada y el recuento de páginas. La deduplicación añade un hash de contenido por página. El performance_budget del front matter es la referencia por combinación.

Notas de seguridad

El recuento de entradas y el tamaño por entrada están acotados por SmartMergeConfig para limitar el agotamiento de recursos por entradas hostiles. La combinación no ejecuta scripts de documento incrustados. Consulta el modelo de seguridad de Core para el endurecimiento del análisis de flujos de bytes.

Conformidad

Afirmación	Cláusula de la especificación	Estado
Marcadores consolidados mediante /Outlines	ISO 32000-2:2020 §7.7.2	Verificado (suite unitaria)
Deduplicación de páginas por hash de contenido	—	Verificado (suite unitaria)
Nueva resolución completa de enlaces entre documentos	—	No admitido (solo detección)

Alternativa / opción de respaldo en Core

Para la concatenación básica sin consolidación de Pro, el NextPDF\Document\PdfMerger de Core de código abierto es la vía autónoma admitida. SmartMerger no delega en él; la combinación de Pro se ejecuta en su propio motor de grafo de objetos. Consulta /modules/core/document/.

Nota sobre el límite de Enterprise

Este módulo realiza una combinación estructural. No realiza ensamblaje para retención legal, redacción ni empaquetado de cadena de custodia probatoria; eso no se proporciona aquí.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de API pública admitida. Las rutas de espacios de nombres internos, las clases auxiliares, las tablas de mecanismos, los nombres de archivos de runbook y los prefijos de tickets quedan fuera del alcance.

Consulta también

• Combinación — Referencia detallada
• Toc
• Diferencias
• Modelo de documento de Core