Combinación — Referencia detallada

De un vistazo

Esta página es la referencia a nivel de contrato del módulo Merge de NextPDF Pro, NextPDF\Pro\Merge. SmartMerger ensambla varios documentos de entrada en uno solo y aplica las mejoras de Pro: un árbol de marcadores consolidado a partir de las etiquetas por entrada, deduplicación de documentos completos, selección de rangos de páginas por entrada y detección de enlaces internos. SemanticSplitter es el punto de entrada complementario de división consciente de la estructura. Esta página expone la API pública, el contrato de comportamiento observable, los límites de recursos y los modos de fallo. La configuración orientada a tareas y los ejemplos están en la página de la capacidad Merge.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Ninguna marca de capacidad en tiempo de ejecución restringe este módulo. Las clases de Merge son utilizables siempre que nextpdf/pro esté instalado y licenciado.

Superficie de la API pública

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	Acepta e ignora el fusionador de núcleo heredado; un divisor null construye el divisor Pro por defecto	—	—	$coreMerger se conserva solo para construcción retrocompatible
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	Reduce rangos de páginas, deduplica entradas completas, delega el ensamblaje base y luego inyecta marcadores y cuenta enlaces según la configuración	SmartMergeResult	InvalidArgumentException con una lista de entradas vacía; OverflowException cuando el número de entradas supera maxInputs o una entrada supera maxBytesPerInput	Único punto de entrada de fusión
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	Objeto de valor; un $pageRanges vacío selecciona todas las páginas	—	—	Readonly
MergeInput::hasPageRanges()	—	Verdadero cuando la entrada lleva al menos un rango de páginas	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	Objeto de valor que contiene los conmutadores de mejora y los límites de recursos	—	—	Readonly; la deduplicación es opcional
SmartMergeConfig::default()	—	Marcadores y escaneo de enlaces activados, deduplicación desactivada	self	—	Fábrica estática
SmartMergeConfig::basic()	—	Todas las mejoras desactivadas; solo concatenación base	self	—	Fábrica estática
SmartMergeResult::__construct()	string $pdfData, int $totalPages, int $sourceCount, int $mergedSize, int $bookmarksAdded = 0, int $duplicatesRemoved = 0, int $linksRewritten = 0, list<string> $inputLabels = []	Portador readonly de los bytes fusionados y las estadísticas de consolidación	—	—	Readonly
SmartMergeResult::isValid()	—	Verdadero cuando la salida comienza con la cabecera %PDF	bool	—	Solo comprobación de cabecera
SmartMergeResult::hasOptimizations()	—	Verdadero cuando se ha eliminado algún duplicado o se ha contado algún enlace	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	Un argumento null construye el divisor Pro por defecto	—	—	Inyección por constructor para pruebas
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	Detecta operadores Tf de tamaño de encabezado como inicios de sección y divide en esos límites; si no se detecta estructura, devuelve una única sección de documento completo	SplitResult	InvalidArgumentException cuando el búfer está vacío o carece de la cabecera %PDF; OverflowException cuando la entrada supera los 100 MB	Recurre a la división por rangos de páginas de Core

Firmas de los puntos de entrada

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

Contrato de comportamiento

Canalización de fusión

SmartMerger::merge() ejecuta una canalización fija, observada externamente como sigue.

1. Una lista de entradas vacía lanza InvalidArgumentException. El número de entradas se acota luego con maxInputs; un exceso lanza OverflowException.
2. Cada entrada se comprueba en tamaño frente a maxBytesPerInput antes de usarse. Cuando la entrada declara rangos de páginas, primero se reduce a las páginas seleccionadas mediante el divisor Pro, y luego aporta únicamente esas páginas.
3. Cuando deduplicatePages está habilitado, la cadena de bytes completa de cada documento de entrada se identifica con la función no criptográfica xxh128. Una entrada cuyos bytes coincidan exactamente con una entrada anterior se descarta. La deduplicación es de documento completo y exacta byte a byte.
4. El ensamblaje base delega en el motor Pro PdfSplitter::mergeDocuments(), que renumera cada entrada en un único espacio de objetos contiguo y emite una tabla de referencias cruzadas real.
5. La consolidación de marcadores se aplica cuando consolidateBookmarks está habilitado y al menos una entrada lleva una etiqueta no vacía. Se inserta un diccionario /Outlines mínimo, enlazado desde el catálogo del documento, con una entrada de esquema por entrada en orden de fusión.
6. Cuando rewriteLinks está habilitado, la salida fusionada se escanea en busca de acciones /S /GoTo y se informa de su número.

Estadísticas del resultado

SmartMergeResult informa de los bytes fusionados más las estadísticas. totalPages proviene de la fusión base. sourceCount es el número de entradas original, tomado antes de la deduplicación. mergedSize es la longitud en bytes de la salida. bookmarksAdded cuenta solo las entradas que aportaron una etiqueta no vacía. duplicatesRemoved cuenta las entradas completas descartadas. linksRewritten es el número de GoTo detectados. inputLabels enumera las etiquetas resueltas en orden de fusión. isValid() comprueba la cabecera %PDF; hasOptimizations() es verdadero cuando se ha eliminado un duplicado o se ha contado un enlace.

Títulos de los marcadores

Cada entrada de esquema lleva la etiqueta de la entrada como un /Title, escapado como cadena literal PDF según ISO 32000-2:2020 §7.3.4.2. La barra invertida se duplica primero, los paréntesis se escapan, los bytes de control con nombre usan sus secuencias definidas y cualquier byte no imprimible restante se convierte en un escape octal de tres dígitos. Por tanto, una etiqueta hostil no puede desincronizar el delimitador de la cadena literal ni inyectar estructura de objetos. Las entradas con una etiqueta vacía reciben un título de marcador de posición Document N, indexado desde uno.

Ensamblaje base

El heredado PdfMerger::merge() de Core es un stub deliberadamente cerrado ante fallos en esta versión; SmartMerger nunca lo invoca. En su lugar, la fusión base se ejecuta a través de Pro PdfSplitter::mergeDocuments(), de modo que el archivo fusionado lleva una tabla de referencias cruzadas exacta en bytes con una entrada por objeto indirecto según ISO 32000-2:2020 §7.5.4. El determinismo sigue el perfil documentado del divisor Pro: entradas y configuración idénticas producen un flujo de bytes estable.

División consciente de la estructura

SemanticSplitter::splitByStructure() escanea los flujos de contenido de página en busca de operadores de fijación de fuente Tf iguales o superiores a headingFontThreshold (por defecto 14.0) y trata cada una de esas páginas como un inicio de sección. Los límites se convierten en rangos de páginas y se delegan en Pro PdfSplitter::split(). Cuando no se detecta ningún límite, el documento completo se devuelve como una única sección. La entrada debe comenzar con %PDF y permanecer dentro del límite de 100 MB.

Casos límite y modos de fallo

• Una lista de entradas vacía falla con InvalidArgumentException antes de cualquier ensamblaje.
• Un número de entradas superior a maxInputs (por defecto 100), o cualquier entrada superior a maxBytesPerInput (por defecto 100 MB), falla con OverflowException. Ambos límites son rechazos deliberados cerrados ante fallos, no errores transitorios.
• La deduplicación es de documento completo y exacta byte a byte. Dos entradas que se rendericen de forma idéntica pero difieran en cualquier byte se retienen ambas, y duplicatesRemoved cuenta las entradas completas descartadas pese al nombre deduplicatePages, orientado a páginas.
• sourceCount refleja el número de entradas original, no el número de documentos posterior a la deduplicación.
• La consolidación de marcadores solo se activa cuando al menos una entrada tiene una etiqueta no vacía. Con consolidateBookmarks verdadero pero todas las etiquetas vacías, no se escribe ningún objeto /Outlines.
• Las entradas de esquema inyectadas llevan títulos y los enlaces de árbol /Parent, /Prev, /Next; no incrustan destinos /Dest explícitos en esta versión.
• La reescritura de enlaces solo cuenta las acciones /S /GoTo; no reapunta los destinos entre objetos renumerados. Conviene tratar linksRewritten como un recuento de detección.
• La detección de SemanticSplitter es léxica. Se basa en los operadores de tamaño de fuente Tf, de modo que las páginas solo con imágenes o con codificación inusual no producen límites y devuelven una única sección de documento completo.

Comportamiento en modo FIPS

En este módulo no ocurre ninguna operación criptográfica, por lo que no existe comportamiento específico del modo FIPS. La huella de contenido xxh128 usada para la deduplicación es un hash de detección de cambios no criptográfico y no tiene ningún peso de integridad ni probatorio.

Conformidad

Afirmación	Norma	Cláusula
Marcadores consolidados escritos como un diccionario /Outlines enlazado desde el catálogo del documento	ISO 32000-2:2020	§7.7.2
La fusión base emite una tabla de referencias cruzadas exacta en bytes para cada objeto indirecto	ISO 32000-2:2020	§7.5.4
Títulos de las entradas de esquema escapados como cadenas literales PDF, con tratamiento de barra invertida y paréntesis	ISO 32000-2:2020	§7.3.4.2
Re-resolución completa de enlaces entre documentos	—	No admitido (solo detección de GoTo)
Destinos de esquema explícitos por sección	—	No emitidos en esta versión

Todas las cláusulas están parafraseadas; NextPDF no reproduce el texto normativo. Son declaraciones de capacidad, no certificaciones; NextPDF no posee ninguna certificación ni concede ninguna.

Notas de desarrollo

• Disponibilidad dentro del paquete Pro: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult y SemanticSplitter desde 2.2.0. Todos vigentes en nextpdf/pro 3.1.0.
• La fusión base delega en Pro PdfSplitter::mergeDocuments(). El heredado PdfMerger::merge() de Core es un stub cerrado ante fallos en esta versión y nunca se llama.
• Habilitar deduplicatePages solo cuando las entradas puedan ser documentos completos byte a byte idénticos; no colapsa copias casi duplicadas ni recodificadas.
• Usar SmartMergeConfig::basic() para la concatenación pura y ::default() para los marcadores más el escaneo de enlaces.
• Capturar OverflowException al fusionar entradas no confiables; los límites de número y tamaño son rechazos intencionados.
• Preferir el PdfSplitter de Pro directamente para la división simple por rangos de páginas; recurrir a SemanticSplitter solo cuando se requiera la seccionación guiada por encabezados.

Límite de publicación

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

Véase también

• Merge (capacidad) — instalación, inicio rápido y ejemplos de producción.
• Toc — Referencia detallada
• Diff — Referencia detallada
• Document — Referencia detallada — divisor Pro y motor de fusión base.