Projection — Referência Profunda

Visão geral

Esta página é a referência profunda do módulo Pro Projection. Ela documenta a superfície pública de tokenização, emissão e ida e volta, o portão de intenção e a semântica de ida e volta de fluxo de conteúdo. O ContentProjectionWriter faz a análise léxica de um fluxo de conteúdo PDF em uma lista de tokens plana e ordenada e, em seguida, re-serializa uma lista de tokens em um novo fluxo de conteúdo. O modelo é unidirecional: a emissão produz um novo fluxo, nunca uma edição no lugar do original.

Nota. “Projection” aqui significa projeção de tokens de fluxo de conteúdo, não projeção de coordenadas ou geoespacial.

Disponibilidade e licenciamento

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

Não existe sinalizador de licença por recurso. Esta é uma capacidade da edição Pro. A emissão exige adicionalmente um argumento ProjectionIntent explícito, imposto pelo sistema de tipos, não por um interruptor de licença.

Superfície da API pública

composer require nextpdf/pro:^3

O módulo reside no namespace NextPDF\Pro\Projection. Todas as operações em ContentProjectionWriter são estáticas.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
ContentProjectionWriter::tokenize	string $contentStream	Faz a análise léxica do fluxo em uma lista de tokens plana e ordenada; normaliza espaço em branco, descarta comentários, ignora bytes não reconhecidos	list<ContentToken>	Nenhum; bytes malformados ou de controle são ignorados, não rejeitados	Somente leitura; não requer intenção.
ContentProjectionWriter::emit	list<ContentToken> $tokens, ProjectionIntent $intent	Serializa os tokens em um novo fluxo de conteúdo; a saída é independente do valor da intenção	string	Nenhum no corpo; um argumento ausente ou não-ProjectionIntent falha na fronteira de tipos	A intenção é um portão no ponto de chamada, não um interruptor em tempo de execução.
ContentProjectionWriter::roundTrip	string $contentStream	Tokeniza e então re-emite sem modificação; o portão de validação	string	Nenhum	A saída não é byte-idêntica; a sequência de operadores e os valores dos operandos são preservados.
ContentToken::__construct	ContentTokenType $type, string|int|float|bool|null $value = null	Constrói um token imutável; não realiza validação	ContentToken	Nenhum; um $value incompatível com o tipo falha na fronteira de tipos	readonly; type e value são públicos.
ContentToken::isTextOperator	—	Informa se o token é um operador de texto (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, ', ")	bool	Nenhum; retorna false para tokens que não são operadores	—
ContentToken::isTextShowingOperator	—	Informa se o token é um operador de exibição de texto (Tj, TJ, ', ")	bool	Nenhum; retorna false para tokens que não são operadores	Subconjunto dos operadores de texto.
ContentTokenType	— (enum com respaldo de string)	Enumera os discriminadores de token: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	Os valores de respaldo são identificadores estáveis.
ProjectionIntent	— (enum puro)	Enumera as duas intenções de emissão permitidas: Sanitization, SteganographicEmbedding	—	—	Não há caso genérico, então a análise estática sinaliza uso não declarado.

public static function tokenize(string $contentStream): array
public static function emit(array $tokens, ProjectionIntent $intent): string
public static function roundTrip(string $contentStream): string

enum ProjectionIntent
{
    case Sanitization;
    case SteganographicEmbedding;
}

public function __construct(
    public ContentTokenType $type,
    public string|int|float|bool|null $value = null,
) {}

public function isTextOperator(): bool
public function isTextShowingOperator(): bool

Contrato de comportamento

ContentProjectionWriter::tokenize($contentStream) faz a análise léxica do fluxo em uma list<ContentToken> plana e ordenada. Ele cobre strings literais, strings hexadecimais, nomes, números, delimitadores de array e de dicionário, booleanos, null e operadores. Espaço em branco e comentários são consumidos e descartados; um byte não reconhecido avança o cursor sem produzir um token. A passagem é somente leitura e não precisa de intenção.

emit($tokens, $intent) serializa uma lista de tokens de volta em bytes de fluxo de conteúdo e requer um ProjectionIntent. A intenção é apenas uma declaração no ponto de chamada: os bytes emitidos são idênticos independentemente de qual caso for passado. Os números mantêm sua distinção inteiro/float — inteiros são emitidos literalmente, floats são emitidos com até seis dígitos fracionários e zeros à direita aparados. Strings literais são reescapadas, strings hexadecimais são emitidas como hexadecimal maiúsculo e nomes carregam sua barra inicial. Cada operador é seguido por uma nova linha; delimitadores de array e de dicionário suprimem o separador adjacente.

roundTrip($contentStream) tokeniza e então re-emite sem alteração. É o portão de validação: confirme um resultado limpo antes de confiar em qualquer sequência de modificar e emitir. A saída não é byte-idêntica à entrada — o espaço em branco é normalizado e os comentários desaparecem —, mas a sequência de operadores e os valores dos operandos são preservados.

ProjectionIntent tem exatamente dois casos: Sanitization (tarjamento destrutivo e irreversível) e SteganographicEmbedding (incorporação de payload oculto). Não há caso genérico, então a análise estática pode sinalizar qualquer emissão que careça de um propósito declarado e conhecido. ContentToken é um valor readonly imutável que carrega um discriminador type e um value decodificado; isTextOperator() e isTextShowingOperator() classificam tokens de operador e retornam false para todo token que não seja operador.

Casos extremos e modos de falha

• Confirme uma ida e volta limpa antes de qualquer sequência de modificar e emitir. Trate uma ida e volta com falha como uma condição de parada.
• A intenção Sanitization é irreversível. Os tokens removidos estão ausentes da saída e não podem ser recuperados dela.
• A intenção não altera a saída. emit() produz os mesmos bytes para qualquer um dos casos; o argumento é um portão no ponto de chamada. Edições de tarjamento e esteganográficas são aplicadas pelo chamador ao mutar a lista de tokens antes da emissão.
• O emissor normaliza o espaço em branco e descarta os comentários, de modo que a comparação em nível de bytes com o original difere mesmo em uma ida e volta sem modificações.
• Operandos float são formatados com no máximo seis dígitos fracionários e então aparados. Valores que precisam de mais precisão são arredondados na emissão; inteiros são exatos.
• Os escapes de string literal decodificados na entrada incluem \n, \r, \t, \b, \f, delimitadores escapados e escapes octais de até três dígitos limitados a um byte.
• Uma string hexadecimal com contagem ímpar de dígitos é preenchida com um zero à direita na entrada, correspondendo à regra de string hexadecimal da ISO.
• Bytes malformados ou de controle são ignorados, não rejeitados; tokenize() não lança nenhuma exceção diante de entrada inesperada.
• Este módulo não realiza nenhuma operação criptográfica e não define nenhum comportamento específico de FIPS.

Conformidade

A tokenização trata o fluxo como uma sequência de operadores e operandos em sintaxe de objeto PDF padrão, conforme a ISO 32000-2:2020, 8.2. O agrupamento de bytes em tokens segue as classes léxicas de caracteres da ISO 32000-2:2020, 7.2. Uma string hexadecimal de comprimento ímpar preenche o dígito final como zero, conforme a ISO 32000-2:2020, 7.3.4.3. Essas cláusulas estão registradas no registro de citações desta página.

Estas declarações descrevem a capacidade em relação às cláusulas citadas. A NextPDF não detém certificação de conformidade, e o suporte a uma cláusula não é uma alegação de certificação.

Notas de desenvolvimento

• Disponível desde a versão 1.10.0 do módulo; todas as três operações são pontos de entrada estáticos em ContentProjectionWriter.
• Tokenização e emissão são lineares no comprimento do fluxo de conteúdo. Não há número de throughput publicado; meça com fluxos representativos.
• O modelo de token plano — um token por elemento léxico, não agrupado por operador — é o que permite edições cirúrgicas, como ajustar um único número dentro de um array TJ. Representações agrupadas por operador residem em outra parte da árvore Pro e estão fora do escopo aqui.
• ContentToken é imutável. Construa uma lista modificada criando novos tokens em vez de mutar os existentes.
• Mantenha o portão de ida e volta no seu pipeline: um roundTrip() bem-sucedido é a pré-condição em torno da qual o módulo foi projetado antes de qualquer edição destrutiva.

Limite de publicação

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

Veja também

• Projection — visão geral da capacidade
• AST — Referência Profunda
• Writer — Referência Profunda