Pro edición

Projection — Referencia detallada

De un vistazo

Esta página es la referencia detallada del módulo Projection de Pro. Documenta la superficie pública de tokenize, emit y round-trip, la puerta de intención y la semántica de ida y vuelta de los flujos de contenido. ContentProjectionWriter analiza léxicamente un flujo de contenido PDF en una lista de tokens plana y ordenada, y luego reserializa una lista de tokens en un nuevo flujo de contenido. El modelo es unidireccional: la emisión produce un flujo nuevo, nunca una edición in situ del original.

Nota. «Projection» aquí significa proyección de tokens de flujos de contenido, no proyección de coordenadas ni geoespacial.

Disponibilidad y licencias

Esta funcionalidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa titularidad no carga las clases de la funcionalidad. Comparar ediciones y obtener una licencia.

No existe ningún indicador de licencia por funcionalidad. Es una funcionalidad de la edición Pro. La emisión requiere además un argumento ProjectionIntent explícito impuesto por el sistema de tipos, no un interruptor de licencia.

Superficie pública de la API

composer require nextpdf/pro:^3

El módulo reside en el espacio de nombres NextPDF\Pro\Projection. Todas las operaciones de ContentProjectionWriter son estáticas.

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
`ContentProjectionWriter::tokenize`	`string $contentStream`	Analiza léxicamente el flujo en una lista de tokens plana y ordenada; normaliza los espacios en blanco, descarta los comentarios, omite los bytes no reconocidos	`list<ContentToken>`	Ninguno; los bytes malformados o de control se omiten, no se rechazan	Solo lectura; no requiere intención.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	Serializa los tokens en un nuevo flujo de contenido; la salida es independiente del valor de la intención	`string`	Ninguno en el cuerpo; un argumento ausente o que no sea `ProjectionIntent` falla en el límite de tipos	La intención es una puerta en el sitio de llamada, no un interruptor en tiempo de ejecución.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	Tokeniza y luego reemite sin modificación; la puerta de validación	`string`	Ninguno	La salida no es idéntica byte a byte; se conservan la secuencia de operadores y los valores de los operandos.
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	Construye un token inmutable; no realiza validación	`ContentToken`	Ninguno; un `$value` de tipo incompatible falla en el límite de tipos	`readonly`; `type` y `value` son públicos.
`ContentToken::isTextOperator`	—	Indica si el token es un operador de texto (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, `'`, `"`)	`bool`	Ninguno; devuelve `false` para los tokens que no son operadores	—
`ContentToken::isTextShowingOperator`	—	Indica si el token es un operador de presentación de texto (Tj, TJ, `'`, `"`)	`bool`	Ninguno; devuelve `false` para los tokens que no son operadores	Subconjunto de los operadores de texto.
`ContentTokenType`	— (enum respaldado por cadena)	Enumera los discriminadores de token: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	Los valores de respaldo son identificadores estables.
`ProjectionIntent`	— (enum puro)	Enumera las dos intenciones de emisión permitidas: Sanitization, SteganographicEmbedding	—	—	No hay caso genérico, por lo que el análisis estático marca el uso no 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 comportamiento

ContentProjectionWriter::tokenize($contentStream) analiza léxicamente el flujo en una list<ContentToken> plana y ordenada. Abarca cadenas literales, cadenas hexadecimales, nombres, números, delimitadores de matrices y diccionarios, booleanos, null y operadores. Los espacios en blanco y los comentarios se consumen y se descartan; un byte no reconocido avanza el cursor sin producir un token. La pasada es de solo lectura y no necesita intención.

emit($tokens, $intent) serializa una lista de tokens de vuelta a bytes de flujo de contenido y requiere un ProjectionIntent. La intención es únicamente una declaración en el sitio de llamada: los bytes emitidos son idénticos con independencia del caso que se pase. Los números mantienen su distinción entre entero y flotante: los enteros se emiten literalmente y los flotantes se emiten con hasta seis dígitos fraccionarios y sin los ceros finales. Las cadenas literales se vuelven a escapar, las cadenas hexadecimales se emiten en hexadecimal en mayúsculas y los nombres llevan su barra inclinada inicial. Cada operador va seguido de un salto de línea; los delimitadores de matrices y diccionarios suprimen el separador adyacente.

roundTrip($contentStream) tokeniza y luego reemite sin cambios. Es la puerta de validación: confirmar un resultado limpio antes de confiar en cualquier secuencia de modificación y emisión. La salida no es idéntica byte a byte a la entrada —los espacios en blanco se normalizan y los comentarios desaparecen— pero se conservan la secuencia de operadores y los valores de los operandos.

ProjectionIntent tiene exactamente dos casos: Sanitization (redacción destructiva e irreversible) y SteganographicEmbedding (embebido de una carga útil oculta). No hay caso genérico, por lo que el análisis estático puede marcar cualquier emisión que carezca de un propósito declarado y conocido. ContentToken es un valor readonly inmutable que lleva un discriminador type y un value decodificado; isTextOperator() e isTextShowingOperator() clasifican los tokens de operador y devuelven false para todo token que no sea operador.

Casos límite y modos de fallo

Confirmar una ida y vuelta limpia antes de cualquier secuencia de modificación y emisión. Tratar una ida y vuelta fallida como una condición de parada.
La intención Sanitization es irreversible. Los tokens eliminados están ausentes de la salida y no pueden recuperarse a partir de ella.
La intención no cambia la salida. emit() produce los mismos bytes en cualquiera de los dos casos; el argumento es una puerta en el sitio de llamada. La redacción y las ediciones esteganográficas las aplica quien llama, mutando la lista de tokens antes de la emisión.
El emisor normaliza los espacios en blanco y descarta los comentarios, de modo que la comparación a nivel de byte con el original difiere incluso en una ida y vuelta sin modificar.
Los operandos flotantes se formatean con como máximo seis dígitos fraccionarios y luego se recortan. Los valores que necesitan más precisión se redondean al emitir; los enteros son exactos.
Los escapes de cadena literal de entrada que se decodifican incluyen \n, \r, \t, \b, \f, los delimitadores escapados y los escapes octales de hasta tres dígitos limitados a un byte.
Una cadena hexadecimal con un número impar de dígitos se rellena con un cero final en la entrada, conforme a la regla ISO de cadenas hexadecimales.
Los bytes malformados o de control se omiten, no se rechazan; tokenize() no lanza ninguna excepción ante una entrada inesperada.
Este módulo no realiza operaciones criptográficas y no define ningún comportamiento específico de FIPS.

Conformidad

La tokenización trata el flujo como una secuencia de operadores y operandos en la sintaxis de objetos estándar de PDF, según ISO 32000-2:2020, 8.2. La agrupación de bytes en tokens sigue las clases léxicas de caracteres de ISO 32000-2:2020, 7.2. Una cadena hexadecimal de longitud impar rellena el dígito final con cero, según ISO 32000-2:2020, 7.3.4.3. Estas cláusulas están registradas en el registro de citas de esta página.

Estas afirmaciones describen la capacidad frente a las cláusulas citadas. NextPDF no posee ninguna certificación de conformidad, y el soporte de una cláusula no constituye una declaración de certificación.

Notas de desarrollo

Disponible desde la versión 1.10.0 del módulo; las tres operaciones son puntos de entrada estáticos en ContentProjectionWriter.
Tokenize y emit son lineales respecto a la longitud del flujo de contenido. No existe una cifra de rendimiento publicada; conviene medir con flujos representativos.
El modelo de tokens plano —un token por elemento léxico, no agrupado por operador— es lo que permite ediciones quirúrgicas como ajustar un único número dentro de una matriz TJ. Las representaciones agrupadas por operador residen en otra parte del árbol de Pro y quedan fuera del alcance aquí.
ContentToken es inmutable. Conviene construir una lista modificada creando tokens nuevos en lugar de mutar los existentes.
Mantener la puerta de ida y vuelta en la canalización: un roundTrip() que pasa es la condición previa en torno a la cual está diseñado el módulo antes de cualquier edición destructiva.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API compatible. Las rutas internas de espacios de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.