Pro edição

Document

Visão geral

O módulo Document divide um PDF em segmentos por intervalo de páginas e monta Portfólios PDF (Coleções) com colunas de esquema ordenáveis. Ambas as operações são limitadas contra entradas hostis.

Disponibilidade e licenciamento

Este recurso vem no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes do recurso. O Document faz parte da edição Pro, sem sinalizador de licença separado por recurso. Compare as edições e obtenha uma licença.

Instalação

composer require nextpdf/pro:^3

O código fica sob o namespace NextPDF\Pro\Document.

Visão conceitual

Duas capacidades são fornecidas:

PdfSplitter extrai intervalos de páginas em segmentos PDF independentes. Ele detecta páginas varrendo objetos de página na entrada bruta e envolve as páginas selecionadas em um catálogo e uma árvore de páginas mínimos. Ele suporta divisão baseada em intervalo, divisão de tamanho fixo (splitEvery) e extração de intervalo único (extractPages).
PdfPortfolio constrói um dicionário PDF Collection que agrega anexos de arquivo com um esquema definido. Ele suporta os modos de visualização tile, detail e hidden, e emite um dicionário adequado para inclusão no catálogo do documento.

Por que funciona assim

Dividir um PDF não é um fatiamento de bytes. Um objeto de página se refere a recursos compartilhados, fontes e fluxos de conteúdo por referência indireta. Ele também herda /MediaBox e /Resources dos ancestrais na árvore de páginas. Por isso, o divisor reconstrói cada segmento como um grafo de objetos autocontido: ele percorre o fecho transitivo de referências das páginas selecionadas, materializa os atributos herdados, renumera em um novo espaço de ids e escreve uma tabela de referências cruzadas com offsets precisos por byte. O percurso do fecho é limitado, porque um grafo hostil com fan-out poderia, do contrário, puxar trabalho ilimitado para um único segmento. O resultado abre como um PDF independente válido, não como um fragmento com referências pendentes.

Contexto de projeto: A anatomia de um arquivo PDF.

Contrato de comportamento

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) impõe um limite de tamanho de entrada e um limite de contagem de intervalos, e rejeita entradas que não comecem com o cabeçalho do PDF.
splitEvery($pdfData, $pagesPerSegment) rejeita um tamanho de segmento abaixo de 1; o segmento final pode conter menos páginas.
PdfPortfolio rejeita qualquer modo de visualização que não seja tile, detail ou hidden no momento da construção.
addSchema() e addEntry() retornam o portfólio para encadeamento fluente; generateCollectionDictionary() retorna a string do dicionário Collection.
Os nomes dos campos do esquema são higienizados para uso como objetos de nome PDF; os valores de string são escapados para strings literais PDF.

Exemplo de código — Início rápido

O que se segue reflete a API pública documentada. O repositório não fornece um exemplo executável para este módulo.

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

Exemplo de código — Produção

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

Casos extremos e armadilhas

O divisor reconstrói cada segmento como um grafo de objetos novo com uma tabela de referências cruzadas real e precisa por byte; os segmentos são PDFs independentes válidos. Ele renumera em um novo espaço de ids em vez de preservar o layout de bytes de origem, então entregue os bytes do segmento ao módulo Writer para fluxos de atualização incremental ou assinatura.
Um intervalo que não corresponde a nenhuma página gera um segmento mínimo de uma página em vez de um erro.
A ordenação do portfólio assume por padrão o primeiro campo do esquema, em ordem crescente.

Desempenho

A divisão e a montagem de portfólio são lineares no tamanho da entrada e na contagem de entradas. O teto de entrada padrão é de 100 MB e o teto de intervalos padrão é 1000; ambos podem ser ajustados para baixo pelo chamador. Meça com documentos representativos.

Notas de segurança

Trate a entrada como não confiável. As proteções de tamanho e contagem limitam o uso de recursos. O módulo higieniza os nomes dos campos e escapa os valores de string antes que cheguem ao dicionário de saída. Ele não registra conteúdo do documento.

Conformidade

O dicionário Portfolio segue o modelo PDF Collections e o divisor segue o modelo de objeto de página definido pela ISO 32000-2; a origem anota as cláusulas relevantes. O corpus RAG estava indisponível no momento da autoria, então esta página não afirma nenhum identificador de cláusula externo e limita as declarações de conformidade ao comportamento verificado pelos testes do módulo.

Nota sobre o limite do Enterprise

O Enterprise não altera o comportamento do Document. O Enterprise acrescenta recursos de arquivamento e compliance de nível superior documentados separadamente; eles não são necessários para divisão ou montagem de Portfólio.

Fallback / alternativa do Core

Sem o Pro, use as primitivas básicas de documento do NextPDF Core; a divisão por intervalo de páginas e a montagem de Portfólio são acréscimos do Pro. Consulte /modules/document/.

Limite de publicação

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