Mesclagem

Visão geral

NextPDF\Pro\Merge\SmartMerger mescla vários PDFs em um único e, em seguida, aplica melhorias do Pro: uma árvore de marcadores consolidada a partir de rótulos por entrada, deduplicação de páginas por hash de conteúdo e seleção de intervalos de páginas por entrada. A montagem do documento base é executada pelo motor de mesclagem de grafo de objetos do Pro. Ele renumera cada entrada em um único espaço de objetos e grava uma tabela de referência cruzada real.

Disponibilidade e licenciamento

Este recurso é fornecido no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem essa habilitação não carrega as classes do recurso. Compare as edições e obtenha uma licença.

As classes de Merge estão disponíveis sempre que o pacote Pro está instalado. Nenhum sinalizador de capacidade em tempo de execução restringe este módulo.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

SmartMerger aceita uma lista de objetos de valor MergeInput. Cada entrada carrega os bytes do PDF de origem, uma lista opcional de intervalos de páginas e um rótulo opcional. Entradas com intervalos de páginas são reduzidas às páginas selecionadas antes da mesclagem. O documento combinado é produzido pelo motor de mesclagem de grafo de objetos do Pro, que renumera cada entrada em um único espaço de objetos contíguo e emite uma tabela de referência cruzada real; a camada do Pro então acrescenta as melhorias solicitadas.

SmartMergeConfig controla as melhorias:

• A consolidação de marcadores insere uma entrada de sumário por entrada rotulada, apontando para o início da seção daquela entrada. Isso segue o modelo de /Outlines do catálogo do documento na ISO 32000-2:2020 §7.7.2.
• A deduplicação de páginas remove páginas duplicadas byte a byte entre entradas, comparadas por hash de conteúdo.
• A reescrita de links procura ações GoTo internas na saída mesclada.

SmartMergeResult informa os bytes mesclados, além de estatísticas: total de páginas, contagem de fontes, tamanho da saída, marcadores adicionados, duplicatas removidas, links detectados e os rótulos de entrada ordenados.

Por que funciona assim

Mesclar PDFs não é concatenação de bytes: cada entrada carrega seus próprios números de objeto, tabela de referência cruzada e árvore de páginas, de modo que uma junção ingênua não abre em nenhum leitor em conformidade. Portanto, o SmartMerger delega a montagem base ao motor de grafo de objetos do Pro (PdfSplitter::mergeDocuments()), que renumera cada entrada em um único espaço de objetos contíguo, reconstrói uma única árvore de páginas e emite uma tabela de referência cruzada real com deslocamentos de bytes verdadeiros. As melhorias do Pro — consolidação de marcadores, deduplicação e detecção de links — então se sobrepõem a essa saída verificada em vez de reimplementar a montagem. A deduplicação de documento inteiro e o tratamento de links apenas por detecção são limites de escopo deliberados que mantêm a mesclagem determinística e segura em entradas não confiáveis.

Contexto de design: A anatomia de um arquivo PDF.

Contrato de comportamento

• Entrada. Uma lista não vazia de MergeInput. Uma lista vazia levanta InvalidArgumentException. A contagem de entradas e o tamanho em bytes por entrada são limitados por SmartMergeConfig (maxInputs, maxBytesPerInput).
• Saída. Um SmartMergeResult. isValid() é verdadeiro quando a saída começa com o cabeçalho %PDF.
• A consolidação de marcadores adiciona uma entrada por entrada que tem um rótulo não vazio, quando consolidateBookmarks está habilitado.
• A deduplicação é opt-in (deduplicatePages, desativada por padrão) e corresponde páginas inteiras por hash de conteúdo, não páginas visualmente semelhantes.
• A reescrita de links na versão atual detecta e conta ações GoTo internas; ela não realiza a re-resolução completa de destinos entre documentos. Trate linksRewritten como uma contagem de detecção.
• Determinismo. Para entradas e configuração idênticas, o fluxo de bytes mesclado é estável, sujeito ao perfil de determinismo documentado do motor de mesclagem do Pro.

Superfície pública da API

Tipo	Categoria	Membros principais
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

Exemplo de código — Início 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";

Exemplo de código — Produção

<?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 extremos e armadilhas

• Uma única entrada é válida e mescla para uma cópia normalizada desse documento.
• A deduplicação compara o conteúdo em bytes de páginas inteiras; páginas que diferem apenas por metadados ou numeração de objetos não são tratadas como duplicatas.
• A seleção de intervalo de páginas em uma entrada é aplicada antes da ordenação da mesclagem.
• linksRewritten é uma contagem de ações detectadas, não uma garantia de que todo alvo de link entre documentos foi reapontado.

Desempenho

O custo é dominado pelo motor de mesclagem do Pro e escala com o total de bytes de entrada e a contagem de páginas. A deduplicação acrescenta um hash de conteúdo por página. O performance_budget do front-matter é a referência por mesclagem.

Notas de segurança

A contagem de entradas e o tamanho por entrada são limitados por SmartMergeConfig para limitar o esgotamento de recursos a partir de entradas hostis. A mesclagem não executa scripts incorporados ao documento. Consulte o modelo de segurança do Core para o reforço da análise de fluxos de bytes.

Conformidade

Declaração	Cláusula da norma	Status
Marcadores consolidados via /Outlines	ISO 32000-2:2020 §7.7.2	Verificado (conjunto de testes unitários)
Deduplicação de páginas por hash de conteúdo	—	Verificado (conjunto de testes unitários)
Re-resolução completa de links entre documentos	—	Não suportada (apenas detecção)

Fallback / alternativa do Core

Para a concatenação básica sem consolidação do Pro, a classe open-source do Core NextPDF\Document\PdfMerger é o caminho autônomo suportado. SmartMerger não delega a ela; a mesclagem do Pro é executada em seu próprio motor de grafo de objetos. Consulte /modules/core/document/.

Nota sobre o limite do Enterprise

Este módulo realiza mesclagem estrutural. Ele não realiza montagem com retenção legal (legal-hold), tarjamento nem empacotamento de cadeia de custódia probatória; esses não são fornecidos aqui.

Limite de publicação

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

Veja também

• Merge — Referência aprofundada
• Toc
• Diff
• Modelo de documento do Core