Pro edición

Proyección

De un vistazo

Projection analiza un flujo de contenido PDF y lo convierte en una lista plana de tokens, y emite un nuevo flujo de contenido a partir de esos tokens. La emisión requiere una intención declarada explícita. Este módulo no es un editor de PDF de propósito general.

Nota. Aquí «Projection» significa proyección de tokens del flujo de contenido. No es proyección de coordenadas ni geoespacial. Para funciones geoespaciales, consulta el módulo Geo.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Compara ediciones y obtén una licencia.

No existe un indicador de licencia por función independiente. Un argumento ProjectionIntent requerido restringe la emisión a nivel de API, no un interruptor de licencia.

Instalación

composer require nextpdf/pro:^3

El código reside en el espacio de nombres NextPDF\Pro\Projection.

Panorama conceptual

ContentProjectionWriter proporciona tres operaciones estáticas:

tokenize() analiza un flujo de contenido y lo convierte en una lista de tokens plana y ordenada. Es de solo lectura y no necesita intención.
emit() escribe un nuevo flujo de contenido a partir de una lista de tokens (posiblemente modificada). Requiere un ProjectionIntent.
roundTrip() tokeniza y luego vuelve a emitir sin cambios, para validación.

La salida es conceptualmente un nuevo flujo de contenido, no una copia editada del original. El emisor normaliza el espacio en blanco y los comentarios, pero mantiene exactos la secuencia de operadores y los valores de los operandos. La enumeración de intención tiene exactamente dos casos —saneamiento (redacción) e incrustación esteganográfica— y deliberadamente no tiene un caso genérico, de modo que el análisis estático pueda detectar un uso no previsto.

Por qué funciona así

Projection se niega a ser un editor de PDF de propósito general. La emisión reconstruye un flujo de contenido nuevo a partir de una lista plana de tokens, de modo que el original nunca se muta en su lugar. Ese modelo unidireccional es lo que hace que la redacción sea fiable: los tokens eliminados están ausentes de la salida, no pintados por encima. Por ello, emit() exige un ProjectionIntent explícito, y la enumeración solo ofrece saneamiento e incrustación esteganográfica —sin caso genérico—. El análisis estático puede entonces señalar cualquier emisión que carezca de un propósito declarado y conocido. El diseño sacrifica la comodidad de edición a cambio de la garantía de que la intención destructiva siempre sea visible en el sitio de la llamada.

Contexto de diseño: La redacción no es un rectángulo negro.

Contrato de comportamiento

tokenize($contentStream) devuelve una lista de tokens que cubre cadenas, nombres, números, arreglos, diccionarios, booleanos, null y operadores.
emit($tokens, $intent) requiere una intención explícita; el sistema de tipos lo impone en el sitio de la llamada.
La salida de roundTrip() no es idéntica a nivel de bytes a la entrada, pero la secuencia de operadores y los valores de los operandos coinciden.
El emisor formatea los números para mantener la distinción entre entero y flotante y vuelve a escapar las cadenas literales.
Las dos intenciones declaradas son el saneamiento (una operación de redacción destructiva e irreversible) y la incrustación esteganográfica.

Ejemplo de código — Inicio rápido

Lo siguiente refleja la API pública documentada. El repositorio no incluye un ejemplo ejecutable para este módulo.

use NextPDF\Pro\Projection\ContentProjectionWriter;

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

Ejemplo de código — Producción

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 límite y trampas

Ejecuta roundTrip() y confirma que se cumple antes de confiar en una secuencia de modificar y emitir. Trata un round-trip fallido como una condición de parada.
La intención de saneamiento es irreversible. El contenido eliminado no puede recuperarse de la salida.
El emisor normaliza el espacio en blanco y descarta los comentarios, de modo que la comparación a nivel de bytes con el original diferirá incluso en un round-trip sin modificar.

Rendimiento

Tokenizar y emitir son lineales respecto a la longitud del flujo de contenido. El tokenizador acota las lecturas de escapes octales y el tratamiento de cadenas hexadecimales. No hay una cifra de rendimiento publicada. Mide con flujos de contenido representativos.

Notas de seguridad

El argumento de intención requerido evita el uso indebido como editor general. La intención de saneamiento es destructiva e irreversible; verifica primero el round-trip y confirma la salida redactada antes de su distribución. Este módulo no registra ningún contenido.

Conformidad

La tokenización sigue las convenciones léxicas y de flujo de contenido de ISO 32000-2; la fuente anota las cláusulas relevantes. El corpus RAG no estaba disponible en el momento de la redacción, por lo que esta página no afirma identificadores de cláusula externos y limita las declaraciones de conformidad al comportamiento verificado por las pruebas del módulo.

Nota sobre el límite de Enterprise

Enterprise no cambia el comportamiento de Projection. Enterprise añade funciones de privacidad y cumplimiento de nivel superior documentadas por separado; no son necesarias para usar la API de proyección.

Alternativa / opción de respaldo en Core

No existe un equivalente en Core. Sin Pro, los llamadores deben construir su propio tokenizador de flujos de contenido; el modelo de proyección restringido por intención es una adición exclusiva de Pro.

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 de espacios de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivos de runbook y los prefijos de tickets quedan fuera del alcance.