Pro edizione

Proiezione

In sintesi

Projection analizza un content stream PDF trasformandolo in un elenco piatto di token ed emette un nuovo content stream a partire da quei token. L’emissione richiede un intento dichiarato esplicito. Questo modulo non è un editor PDF generico.

Nota. Qui «Projection» indica la proiezione dei token del content stream. Non è la proiezione di coordinate o geospaziale. Per le funzionalità geospaziali, vedere il modulo Geo.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di tier Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Non esiste un flag di licenza separato per ciascuna funzionalità. Un argomento ProjectionIntent obbligatorio controlla l’emissione a livello di API, non un interruttore di licenza.

Installazione

composer require nextpdf/pro:^3

Il codice risiede sotto il namespace NextPDF\Pro\Projection.

Panoramica concettuale

ContentProjectionWriter offre tre operazioni statiche:

tokenize() analizza un content stream trasformandolo in un elenco piatto e ordinato di token. È in sola lettura e non richiede alcun intento.
emit() scrive un nuovo content stream a partire da un elenco di token (eventualmente modificato). Richiede un ProjectionIntent.
roundTrip() tokenizza e poi ri-emette senza modifiche, a fini di convalida.

L’output è concettualmente un nuovo content stream, non una copia modificata dell’originale. L’emettitore normalizza spaziatura e commenti, ma mantiene esatti la sequenza degli operatori e i valori degli operandi. L’enum di intento ha esattamente due casi — sanificazione (oscuramento) e incorporazione steganografica — e deliberatamente non ha un caso generico, così che l’analisi statica possa rilevare un uso indesiderato.

Perché funziona così

Projection rifiuta di essere un editor PDF generico. L’emissione ricostruisce un content stream nuovo a partire da un elenco piatto di token, quindi l’originale non viene mai mutato sul posto. È questo modello a senso unico a rendere affidabile l’oscuramento: i token rimossi sono assenti dall’output, non coperti sopra. Per questo emit() esige un ProjectionIntent esplicito, e l’enum offre solo la sanificazione e l’incorporazione steganografica — nessun caso generico. L’analisi statica può così segnalare qualsiasi emissione priva di uno scopo dichiarato e noto. Il design baratta la comodità di editing con la garanzia che l’intento distruttivo sia sempre visibile nel punto di chiamata.

Contesto di progettazione: L’oscuramento non è un rettangolo nero.

Contratto di comportamento

tokenize($contentStream) restituisce un elenco di token che copre stringhe, nomi, numeri, array, dizionari, booleani, null e operatori.
emit($tokens, $intent) richiede un intento esplicito; il sistema dei tipi lo impone nel punto di chiamata.
L’output di roundTrip() non è byte-identico all’input, ma la sequenza degli operatori e i valori degli operandi corrispondono.
L’emettitore formatta i numeri per mantenere la distinzione tra intero e float e riapplica l’escape alle stringhe letterali.
I due intenti dichiarati sono la sanificazione (un’operazione di oscuramento distruttiva e irreversibile) e l’incorporazione steganografica.

Esempio di codice — Avvio rapido

Quanto segue rispecchia l’API pubblica documentata. Il repository non include un esempio eseguibile per questo modulo.

use NextPDF\Pro\Projection\ContentProjectionWriter;

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

Esempio di codice — Produzione

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);

Casi limite e insidie

Eseguire roundTrip() e confermare che regga prima di fidarsi di una sequenza di modifica-ed-emissione. Trattare un round-trip che fallisce come una condizione di arresto.
L’intento di sanificazione è irreversibile. Il contenuto rimosso non può essere recuperato dall’output.
L’emettitore normalizza la spaziatura e scarta i commenti, quindi un confronto a livello di byte con l’originale differirà anche per un round-trip non modificato.

Prestazioni

Tokenizzazione ed emissione sono lineari rispetto alla lunghezza del content stream. Il tokenizer limita le letture di escape ottali e la gestione delle stringhe esadecimali. Non esiste una cifra di throughput pubblicata. Misurare con content stream rappresentativi.

Note sulla sicurezza

L’argomento di intento obbligatorio impedisce l’uso improprio come editor generico. L’intento di sanificazione è distruttivo e irreversibile; verificare prima il round-trip e confermare l’output oscurato prima della distribuzione. Questo modulo non registra alcun contenuto.

Conformità

La tokenizzazione segue le convenzioni lessicali e di content stream descritte in ISO 32000-2; la sorgente annota le clausole pertinenti. Il corpus RAG non era disponibile al momento della stesura, quindi questa pagina non asserisce alcun identificatore di clausola esterno e limita le dichiarazioni di conformità al comportamento verificato dai test del modulo.

Nota sul confine Enterprise

Enterprise non modifica il comportamento di Projection. Enterprise aggiunge funzionalità di privacy e compliance di tier superiore documentate separatamente; non sono richieste per usare l’API di projection.

Fallback / alternativa di Core

Non esiste un equivalente in Core. Senza Pro, i chiamanti devono costruire il proprio tokenizer di content stream; il modello di projection soggetto a gate per intento è un’aggiunta esclusiva di Pro.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile dall’esterno e la superficie pubblica supportata dell’API. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.