Pro edição

Projeção

Visão geral

A Projection analisa um fluxo de conteúdo de PDF em uma lista plana de tokens e emite um novo fluxo de conteúdo a partir desses tokens. A emissão requer uma intenção declarada explícita. Este módulo não é um editor de PDF de uso geral.

Nota. “Projection” aqui significa projeção de tokens de fluxo de conteúdo. Não é projeção de coordenadas nem geoespacial. Para recursos geoespaciais, consulte o módulo Geo.

Disponibilidade e licenciamento

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

Não há um sinalizador de licença separado por recurso. Um argumento ProjectionIntent obrigatório restringe a emissão no nível da API, não uma chave de licença.

Instalação

composer require nextpdf/pro:^3

O código está sob o namespace NextPDF\Pro\Projection.

Visão conceitual

ContentProjectionWriter fornece três operações estáticas:

tokenize() analisa um fluxo de conteúdo em uma lista plana e ordenada de tokens. Isso é somente leitura e não precisa de intenção.
emit() escreve um novo fluxo de conteúdo a partir de uma lista de tokens (possivelmente modificada). Ele requer um ProjectionIntent.
roundTrip() faz a tokenização e, em seguida, reemite sem alterações, para validação.

A saída é conceitualmente um novo fluxo de conteúdo, não uma cópia editada do original. O emissor normaliza espaços em branco e comentários, mas mantém a sequência de operadores e os valores de operandos exatos. O enum de intenção tem exatamente dois casos — sanitização (tarjamento) e incorporação esteganográfica — e deliberadamente não tem um caso genérico, para que a análise estática possa detectar uso não intencional.

Por que funciona assim

A Projection se recusa a ser um editor de PDF de uso geral. A emissão reconstrói um fluxo de conteúdo novo a partir de uma lista plana de tokens, então o original nunca é mutado no lugar. Esse modelo unidirecional é o que torna o tarjamento confiável: os tokens removidos estão ausentes da saída, não pintados por cima. Portanto, emit() exige um ProjectionIntent explícito, e o enum oferece apenas sanitização e incorporação esteganográfica — sem caso genérico. A análise estática pode então sinalizar qualquer emissão que careça de um propósito declarado e conhecido. O design troca a conveniência de edição por uma garantia de que a intenção destrutiva é sempre visível no ponto de chamada.

Contexto de design: Tarjamento não é um retângulo preto.

Contrato de comportamento

tokenize($contentStream) retorna uma lista de tokens que abrange strings, names, números, arrays, dicionários, booleanos, null e operadores.
emit($tokens, $intent) requer uma intenção explícita; o sistema de tipos impõe isso no ponto de chamada.
A saída de roundTrip() não é byte a byte idêntica à entrada, mas a sequência de operadores e os valores de operandos coincidem.
O emissor formata os números para manter a distinção entre inteiro e ponto flutuante e reescapa strings literais.
As duas intenções declaradas são sanitização (uma operação de tarjamento destrutiva e irreversível) e incorporação esteganográfica.

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

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

use NextPDF\Pro\Projection\ContentProjectionWriter;

$tokens = ContentProjectionWriter::tokenize($contentStream);

Exemplo de código — Produção

use NextPDF\Pro\Projection\ContentProjectionWriter;
use NextPDF\Pro\Projection\ProjectionIntent;

$tokens = ContentProjectionWriter::tokenize($contentStream);

// Validate first: a clean round-trip must hold before any modification.
$check = ContentProjectionWriter::roundTrip($contentStream);

// Apply your modification to $tokens, then emit with a declared intent.
$output = ContentProjectionWriter::emit($tokens, ProjectionIntent::Sanitization);

Casos extremos e armadilhas

Execute roundTrip() e confirme que ele se mantém antes de confiar em uma sequência de modificar e emitir. Trate um round-trip com falha como uma condição de parada.
A intenção de sanitização é irreversível. O conteúdo removido não pode ser recuperado a partir da saída.
O emissor normaliza espaços em branco e descarta comentários, então a comparação em nível de byte com o original diferirá mesmo para um round-trip não modificado.

Desempenho

A tokenização e a emissão são lineares em relação ao comprimento do fluxo de conteúdo. O tokenizador limita as leituras de escape octal e o tratamento de strings hexadecimais. Não há um valor de throughput publicado. Meça com fluxos de conteúdo representativos.

Notas de segurança

O argumento de intenção obrigatório evita o uso indevido como um editor de uso geral. A intenção de sanitização é destrutiva e irreversível; verifique o round-trip primeiro e confirme a saída tarjada antes da distribuição. Este módulo não registra nenhum conteúdo.

Conformidade

A tokenização segue as convenções léxicas e de fluxo de conteúdo da ISO 32000-2; a fonte anota as cláusulas relevantes. O corpus de 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 da Projection. O Enterprise acrescenta recursos de privacidade e conformidade de nível superior documentados separadamente; eles não são necessários para usar a API de projeção.

Fallback / alternativa do Core

Não há equivalente no Core. Sem o Pro, os chamadores precisam construir seu próprio tokenizador de fluxo de conteúdo; o modelo de projeção restrito por intenção é uma adição exclusiva do Pro.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API 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.