Merge — Referência Profunda

Em resumo

Esta página é a referência em nível de contrato para o módulo Merge do NextPDF Pro, NextPDF\Pro\Merge. SmartMerger monta vários documentos de entrada em um só e aplica os aprimoramentos do Pro: uma árvore de marcadores consolidada a partir dos rótulos por entrada, deduplicação de documento inteiro, seleção de intervalo de páginas por entrada e detecção de links internos. SemanticSplitter é o ponto de entrada complementar de divisão consciente da estrutura. Esta página estabelece a API pública, o contrato de comportamento observável, os limites de recursos e os modos de falha. A configuração orientada a tarefas e os exemplos ficam na página de capacidade Merge.

Disponibilidade & licenciamento

Esta capacidade acompanha o NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem essa habilitação não carrega as classes da capacidade. Compare edições e obtenha uma licença.

Nenhum sinalizador de capacidade em tempo de execução restringe este módulo. As classes de Merge ficam utilizáveis sempre que nextpdf/pro estiver instalado e licenciado.

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	Aceita e ignora o core merger legado; um splitter null constrói o splitter Pro padrão	—	—	$coreMerger mantido apenas para construção retrocompatível
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	Reduz intervalos de páginas, deduplica entradas inteiras, delega a montagem base, depois injeta marcadores e conta links conforme a config	SmartMergeResult	InvalidArgumentException em uma lista de entrada vazia; OverflowException quando a contagem de entradas excede maxInputs ou uma entrada excede maxBytesPerInput	Único ponto de entrada de mesclagem
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	Objeto de valor; um $pageRanges vazio seleciona todas as páginas	—	—	Readonly
MergeInput::hasPageRanges()	—	Verdadeiro quando a entrada carrega pelo menos um intervalo 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 mantém os interruptores de aprimoramento e os limites de recursos	—	—	Readonly; a deduplicação é opt-in
SmartMergeConfig::default()	—	Marcadores e varredura de links ligados, deduplicação desligada	self	—	Fábrica estática
SmartMergeConfig::basic()	—	Todos os aprimoramentos desligados; apenas concatenação 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 para os bytes mesclados e as estatísticas de consolidação	—	—	Readonly
SmartMergeResult::isValid()	—	Verdadeiro quando a saída começa com o cabeçalho %PDF	bool	—	Apenas verificação de cabeçalho
SmartMergeResult::hasOptimizations()	—	Verdadeiro quando algum duplicado foi removido ou algum link contado	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	Um argumento null constrói o splitter Pro padrão	—	—	Injeção via construtor para testes
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	Detecta operadores Tf do tamanho de título como início de seção e divide nessas fronteiras; nenhuma estrutura detectada retorna uma única seção de documento inteiro	SplitResult	InvalidArgumentException quando o buffer está vazio ou não tem o cabeçalho %PDF; OverflowException quando a entrada excede 100 MB	Recorre à divisão por intervalo de páginas do Core

Assinaturas dos pontos 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 comportamento

Pipeline de mesclagem

SmartMerger::merge() executa um pipeline fixo, observado externamente como segue.

1. Uma lista de entrada vazia gera InvalidArgumentException. A contagem de entradas é então limitada por maxInputs; um estouro gera OverflowException.
2. Cada entrada tem o tamanho verificado contra maxBytesPerInput antes do uso. Quando a entrada declara intervalos de páginas, ela é primeiro reduzida às páginas selecionadas por meio do splitter Pro e então contribui apenas com essas páginas.
3. Quando deduplicatePages está habilitado, a string de bytes completa de cada documento de entrada recebe uma impressão digital com a função não criptográfica xxh128. Uma entrada cujos bytes correspondem exatamente a uma entrada anterior é descartada. A deduplicação é de documento inteiro e exata em bytes.
4. A montagem base delega ao motor Pro PdfSplitter::mergeDocuments(), que renumera cada entrada em um espaço de objetos contíguo e emite uma tabela de referência cruzada real.
5. A consolidação de marcadores é aplicada quando consolidateBookmarks está habilitado e ao menos uma entrada carrega um rótulo não vazio. Um dicionário /Outlines mínimo é inserido, vinculado a partir do catálogo do documento, com uma entrada de outline por entrada na ordem de mesclagem.
6. Quando rewriteLinks está habilitado, a saída mesclada é varrida em busca de ações /S /GoTo e sua contagem é reportada.

Estatísticas do resultado

SmartMergeResult reporta os bytes mesclados mais estatísticas. totalPages vem da mesclagem base. sourceCount é a contagem original de entradas, tomada antes da deduplicação. mergedSize é o comprimento em bytes da saída. bookmarksAdded conta apenas as entradas que forneceram um rótulo não vazio. duplicatesRemoved conta as entradas inteiras descartadas. linksRewritten é a contagem de GoTo detectada. inputLabels lista os rótulos resolvidos na ordem de mesclagem. isValid() verifica o cabeçalho %PDF; hasOptimizations() é verdadeiro quando um duplicado foi removido ou um link contado.

Títulos de marcadores

Cada entrada de outline carrega o rótulo da entrada como um /Title, escapado como uma string literal PDF conforme ISO 32000-2:2020 §7.3.4.2. A barra invertida (reverse solidus) é duplicada primeiro, os parênteses são escapados, os bytes de controle nomeados usam suas sequências definidas, e qualquer byte não imprimível remanescente vira um escape octal de três dígitos. Um rótulo hostil, portanto, não pode dessincronizar o delimitador de string literal nem injetar estrutura de objetos. Entradas com rótulo vazio recebem um título de placeholder Document N, indexado a partir de um.

Montagem base

O PdfMerger::merge() legado do Core é um stub deliberadamente fail-closed nesta versão; ele nunca é invocado por SmartMerger. A mesclagem base é executada, em vez disso, por meio de PdfSplitter::mergeDocuments() do Pro, de modo que o arquivo mesclado carrega uma tabela de referência cruzada precisa em bytes com uma entrada por objeto indireto, conforme ISO 32000-2:2020 §7.5.4. O determinismo segue o perfil documentado do splitter Pro: entradas e configuração idênticas produzem um fluxo de bytes estável.

Divisão consciente da estrutura

SemanticSplitter::splitByStructure() varre os fluxos de conteúdo de página em busca de operadores de definição de fonte Tf no limiar headingFontThreshold (padrão 14.0) ou acima dele e trata cada página desse tipo como um início de seção. As fronteiras são convertidas em intervalos de páginas e delegadas a PdfSplitter::split() do Pro. Quando nenhuma fronteira é detectada, o documento inteiro retorna como uma única seção. A entrada precisa começar com %PDF e permanecer dentro do limite de 100 MB.

Casos extremos & modos de falha

• Uma lista de entrada vazia falha com InvalidArgumentException antes de qualquer montagem.
• Uma contagem de entradas acima de maxInputs (padrão 100), ou qualquer entrada acima de maxBytesPerInput (padrão 100 MB), falha com OverflowException. Ambos os limites são rejeições deliberadas fail-closed, não erros transitórios.
• A deduplicação é de documento inteiro e exata em bytes. Duas entradas que renderizam de forma idêntica, mas diferem em qualquer byte, são ambas mantidas, e duplicatesRemoved conta as entradas inteiras descartadas, apesar do nome deduplicatePages orientado a páginas.
• sourceCount reflete a contagem original de entradas, não a contagem de documentos após a deduplicação.
• A consolidação de marcadores só dispara quando ao menos uma entrada tem um rótulo não vazio. Com consolidateBookmarks verdadeiro, mas todos os rótulos vazios, nenhum objeto /Outlines é gravado.
• As entradas de outline injetadas carregam títulos e os links de árvore /Parent, /Prev, /Next; elas não embutem destinos /Dest explícitos nesta versão.
• A reescrita de links conta apenas ações /S /GoTo; ela não reaponta destinos entre objetos renumerados. Trate linksRewritten como uma contagem de detecção.
• A detecção do SemanticSplitter é lexical. Ela se baseia em operadores de tamanho de fonte Tf, então páginas apenas de imagem ou codificadas de forma incomum não produzem fronteiras e retornam uma única seção de documento inteiro.

Comportamento em modo FIPS

Nenhuma operação criptográfica ocorre neste módulo, portanto não existe nenhum comportamento específico de modo FIPS. A impressão digital de conteúdo xxh128 usada para deduplicação é um hash não criptográfico de detecção de mudança e não carrega nenhum peso de integridade ou probatório.

Conformidade

Alegação	Padrão	Cláusula
Marcadores consolidados gravados como um dicionário /Outlines vinculado a partir do catálogo do documento	ISO 32000-2:2020	§7.7.2
A mesclagem base emite uma tabela de referência cruzada precisa em bytes para cada objeto indireto	ISO 32000-2:2020	§7.5.4
Títulos das entradas de outline escapados como strings literais PDF, com tratamento de barra invertida e parênteses	ISO 32000-2:2020	§7.3.4.2
Re-resolução completa de links entre documentos	—	Não suportado (apenas detecção de GoTo)
Destinos de outline explícitos por seção	—	Não emitido nesta versão

Todas as cláusulas são parafraseadas; o NextPDF não reproduz texto normativo. Estas são declarações de capacidade, não certificações; o NextPDF não detém nenhuma certificação e não concede nenhuma.

Notas de desenvolvimento

• Disponibilidade dentro do pacote Pro: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult e SemanticSplitter desde 2.2.0. Todos são atuais em nextpdf/pro 3.1.0.
• A mesclagem base delega a PdfSplitter::mergeDocuments() do Pro. O PdfMerger::merge() legado do Core é um stub fail-closed nesta versão e nunca é chamado.
• Habilite deduplicatePages apenas quando as entradas puderem ser documentos inteiros idênticos em bytes; ele não colapsa cópias quase duplicadas nem recodificadas.
• Use SmartMergeConfig::basic() para concatenação pura e ::default() para marcadores mais a varredura de links.
• Capture OverflowException ao mesclar entrada não confiável; os limites de contagem e tamanho são rejeições intencionais.
• Prefira o PdfSplitter do Pro diretamente para divisão simples por intervalo de páginas; recorra ao SemanticSplitter apenas quando a seccionação orientada por títulos for necessária.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície da API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tíquetes estão fora de escopo.

Veja também

• Merge (capacidade) — instalação, início rápido e exemplos de produção.
• Toc — Referência Profunda
• Diff — Referência Profunda
• Document — Referência Profunda — splitter do Pro e motor de mesclagem base.