Pro edição

Document — Referência Profunda

Em resumo

O módulo Document fornece três primitivas de montagem do Pro: divisão por intervalo de páginas, mesclagem de múltiplos documentos e construção do dicionário PDF Portfolio (Collection). O PdfSplitter extrai intervalos de páginas para PDFs autônomos e estruturalmente conformes e mescla documentos inteiros em um único arquivo renumerado. O PdfPortfolio constrói o dicionário Collection que apresenta arquivos incorporados com colunas de esquema ordenáveis. Cada ponto de entrada limita o tamanho da entrada e a contagem de objetos contra entradas hostis.

Disponibilidade e licenciamento

Este recurso é distribuído 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.

Superfície da API pública

Todos os tipos do módulo residem no namespace NextPDF\Pro\Document. PageRange e MergeResult são objetos de valor do Core, de NextPDF\Document.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`PdfSplitter::split()`	`string $pdfData`, `list<PageRange> $ranges`, `int $maxBytes = 100_000_000`, `int $maxRanges = 1000`	Cria um segmento de PDF autônomo por intervalo	`SplitResult`	`InvalidArgumentException` se faltar o cabeçalho `%PDF`; `OverflowException` na proteção de tamanho, contagem de intervalos ou closure	As proteções são executadas antes de qualquer análise
`PdfSplitter::splitEvery()`	`string $pdfData`, `int $pagesPerSegment`	Deriva intervalos contíguos de N páginas; o último segmento pode ser menor	`SplitResult`	`InvalidArgumentException` quando `$pagesPerSegment < 1` ou o cabeçalho está ausente	Delega a `split()` com os tetos padrão
`PdfSplitter::extractPages()`	`string $pdfData`, `PageRange $range`	Retorna um intervalo como bytes de PDF autônomo	`string`	`InvalidArgumentException` se faltar o cabeçalho; `OverflowException` na proteção de closure	Sem parâmetros de teto neste caminho
`PdfSplitter::mergeDocuments()`	`list<string> $pdfs`, `int $maxInputs = 100`, `int $maxBytesEach = 100_000_000`	Mescla as entradas em ordem em um único PDF renumerado	`MergeResult`	`InvalidArgumentException` numa lista vazia ou entrada não PDF; `OverflowException` na proteção de contagem, tamanho por entrada ou closure	Desde 3.1.0; a maior versão de entrada define o cabeçalho de saída
`SplitResult`	`$segments`, `$ranges`, `$totalPages` readonly	Carrega os bytes brutos dos segmentos mais os metadados de origem	—	—	Objeto de valor `final readonly`
`SplitResult::count()`	—	Conta os segmentos produzidos	`int`	—	—
`SplitResult::segment()`	`int $index`	Retorna os bytes de um segmento	`string`	`OutOfRangeException` num índice fora dos limites	Índice baseado em zero
`PdfPortfolio::__construct()`	`string $viewMode = 'tile'`	Valida o modo de visualização na construção	—	`InvalidArgumentException` num modo diferente de `tile`, `detail`, `hidden`	—
`PdfPortfolio::addSchema()`	`PortfolioField $field`	Anexa uma coluna de esquema	`self`	—	Fluente
`PdfPortfolio::addEntry()`	`PortfolioEntry $entry`	Anexa uma entrada de arquivo	`self`	—	Fluente
`PdfPortfolio::getSchema()`	—	Retorna os campos de esquema acumulados	`list<PortfolioField>`	—	—
`PdfPortfolio::getEntries()`	—	Retorna as entradas de arquivo acumuladas	`list<PortfolioEntry>`	—	—
`PdfPortfolio::count()`	—	Conta as entradas de arquivo	`int`	—	—
`PdfPortfolio::generateCollectionDictionary()`	—	Emite a string do dicionário Collection	`string`	—	Os blocos de esquema e ordenação aparecem apenas quando existem campos
`PortfolioEntry`	`$filename`, `$data`, `$description = ''`, `$mimeType = 'application/octet-stream'`, `$customFields = []`	Objeto de valor imutável de entrada de arquivo	—	—	`size()` retorna o comprimento em bytes dos dados
`PortfolioField`	`$name`, `PortfolioFieldType $type`, `$displayName = ''`, `$order = 0`, `$visible = true`	Objeto de valor imutável de coluna de esquema	—	—	`effectiveDisplayName()` recorre a `$name`
`PortfolioFieldType`	Enum de string: `Text`, `Date`, `Number`, `FileName`, `Description`, `Size`, `ModDate`, `CreationDate`	Mapeia cada caso a um `/Subtype` de PDF via `pdfSubtype()`	`string` (`S`, `D`, `N`, `F`, `Desc`)	—	Os casos de data compartilham o subtipo `D`; os casos numéricos compartilham `N`

Assinaturas dos pontos de entrada:

public function split(string $pdfData, array $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000): SplitResult

public function mergeDocuments(
    array $pdfs,
    int $maxInputs = 100,
    int $maxBytesEach = 100_000_000,
): MergeResult

public function __construct(
    private readonly string $viewMode = 'tile',
)

public function generateCollectionDictionary(): string

Contrato de comportamento

A divisão e a mesclagem compartilham um único pipeline de grafo de objetos:

A entrada deve começar com o cabeçalho %PDF. As proteções de tamanho e contagem são executadas antes da análise e lançam OverflowException em caso de violação.
As páginas-folha são detectadas varrendo os marcadores de objeto de página; os nós da árvore de páginas são excluídos da contagem.
O parser indexa cada objeto indireto não comprimido com uma varredura de terminador ciente de streams. A primeira ocorrência de um id de objeto prevalece, portanto as sobreposições de atualização incremental não são aplicadas.
Os atributos herdáveis da árvore de páginas (/Resources, /MediaBox, /CropBox, /Rotate) são materializados em cada página extraída percorrendo sua cadeia /Parent, de modo que os segmentos são autocontidos.
O fechamento transitivo de referências indiretas de cada página é coletado, excluindo a aresta de retorno /Parent, e renumerado para um espaço de ids contíguo e novo.
O serializador emite o cabeçalho, o Catalog, a árvore Pages, os objetos de página e os objetos do fechamento, seguidos por uma tabela de referência cruzada com deslocamentos de bytes precisos e um startxref que aponta para a palavra-chave xref.
mergeDocuments repete o pipeline por entrada em um único espaço de ids compartilhado. A maior versão de PDF de entrada define o cabeçalho de saída. É a substituição conforme para o mesclador desabilitado do Core, que permanece fail-closed.
A saída é determinística. Nenhum timestamp ou identificador aleatório é emitido, portanto entradas idênticas produzem bytes idênticos.

Montagem do Portfolio:

O construtor valida o modo de visualização. O token /View emitido é /T, /D ou /H para tile, detail e hidden, respectivamente.
generateCollectionDictionary() emite /Type /Collection, o token /View, um bloco /Schema quando existem campos e uma diretiva /Sort no primeiro campo de esquema, em ordem crescente.
Cada campo de esquema emite /Subtype (de pdfSubtype()), /N (nome de exibição escapado), /O (ordem) e /V (visibilidade).
Os nomes de campo são sanitizados para tokens de nome PDF válidos; caracteres não alfanuméricos tornam-se sublinhados. Os valores de string são escapados como strings literais de PDF.
As entradas de arquivo são expostas por meio de getEntries() para incorporação pela camada de escrita. O próprio dicionário Collection carrega apenas visualização, esquema e ordenação.

Casos extremos e modos de falha

Um intervalo que não corresponde a nenhuma página produz um segmento mínimo de uma página (MediaBox 612 x 792), não um erro.
Um documento sem marcadores de página detectáveis é contado como uma página.
Páginas armazenadas dentro de object streams não são detectadas; apenas objetos indiretos não comprimidos participam da extração.
Quando existem ids de objeto duplicados, a revisão de menor deslocamento é usada; revisões posteriores de atualização incremental são ignoradas.
O fechamento de referências por segmento é limitado a 50.000 objetos; um grafo maliciosamente autorreferencial ou com fan-out excessivo lança OverflowException.
Tetos padrão: 100 MB de entrada, 1.000 intervalos, 100 entradas de mesclagem. Todos são ajustáveis pelo chamador por chamada.
splitEvery() rejeita um tamanho de segmento abaixo de 1 com InvalidArgumentException.
SplitResult::segment() rejeita um índice fora dos limites com OutOfRangeException.
Dois nomes de campo de esquema que diferem apenas na pontuação são sanitizados para a mesma chave de dicionário; o campo posterior silenciosamente eclipsa o anterior no esquema emitido.
Este módulo não realiza operações criptográficas; o modo FIPS não altera seu comportamento.

Conformidade

A saída de segmentos e de mesclagem segue o modelo de objeto de página da ISO 32000-2; a origem anota as cláusulas relevantes. Afirmações verificáveis externamente:

O layout do trailer, o deslocamento de bytes do startxref e o terminador %%EOF seguem a ISO 32000-2:2020, §7.5.5 — referência ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845.
Os valores /View do dicionário Collection (/T, /D, /H) seguem a ISO 32000-2:2020, §12.3.5 — referência 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd.
As entradas /Subtype, /N, /O e /V do campo de Collection seguem a ISO 32000-2:2020, §12.3.5 (dicionário de campo de collection) — referência 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a.

Estas afirmações descrevem capacidades implementadas e verificadas pelos testes do módulo. O suporte a uma construção não é uma declaração de conformidade, e conformidade não é certificação; o NextPDF não possui certificação de terceiros para este módulo.

Notas de desenvolvimento

Todas as classes do módulo são final; os tipos de resultado e de objeto de valor são readonly. Os tipos do splitter e do Portfolio datam da 1.9.0; mergeDocuments() foi adicionado na 3.1.0.
PageRange e MergeResult são tipos do Core, portanto os pontos de chamada permanecem portáveis entre edições.
Os trailers dos segmentos carregam apenas /Size e /Root; nenhum identificador de arquivo /ID ou dicionário /Info é emitido.
Para fluxos de atualização incremental ou de assinatura, entregue os bytes dos segmentos ao módulo Writer em vez de editá-los diretamente no local.
O módulo não registra nenhum conteúdo do documento.

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 ticket estão fora do escopo.