Pro edizione

Projection — Riferimento approfondito

In breve

Questa pagina è il riferimento approfondito per il modulo Pro Projection. Documenta la superficie pubblica di tokenizzazione, emissione e round-trip, il gate di intento e la semantica di round-trip del content stream. ContentProjectionWriter analizza lessicalmente un content stream PDF producendo una lista di token piatta e ordinata, quindi riserializza una lista di token in un nuovo content stream. Il modello è unidirezionale: l’emissione produce un nuovo stream, mai una modifica in loco dell’originale.

Nota. Qui «proiezione» indica la proiezione di token del content stream, non la proiezione di coordinate o geospaziale.

Disponibilità e licenze

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

Non esiste alcun flag di licenza per singola funzionalità. Si tratta di una funzionalità dell’edizione Pro. L’emissione richiede inoltre un argomento ProjectionIntent esplicito, imposto dal sistema dei tipi e non da un interruttore di licenza.

Superficie API pubblica

composer require nextpdf/pro:^3

Il modulo risiede nel namespace NextPDF\Pro\Projection. Tutte le operazioni su ContentProjectionWriter sono statiche.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
`ContentProjectionWriter::tokenize`	`string $contentStream`	Analizza lessicalmente lo stream in una lista di token piatta e ordinata; normalizza gli spazi, elimina i commenti, ignora i byte non riconosciuti	`list<ContentToken>`	Nessuno; i byte malformati o di controllo vengono ignorati, non rifiutati	Di sola lettura; non richiede alcun intento.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	Serializza i token in un nuovo content stream; l’output è indipendente dal valore dell’intento	`string`	Nessuno nel corpo; un argomento mancante o non `ProjectionIntent` fallisce al confine dei tipi	L’intento è un gate al call site, non un interruttore a runtime.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	Tokenizza e riemette senza modifiche; è il gate di validazione	`string`	Nessuno	L’output non è identico byte per byte; la sequenza degli operatori e i valori degli operandi sono preservati.
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	Costruisce un token immutabile; non esegue alcuna validazione	`ContentToken`	Nessuno; un `$value` incompatibile con il tipo fallisce al confine dei tipi	`readonly`; `type` e `value` sono pubblici.
`ContentToken::isTextOperator`	—	Indica se il token è un operatore di testo (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, `'`, `"`)	`bool`	Nessuno; restituisce `false` per i token non operatore	—
`ContentToken::isTextShowingOperator`	—	Indica se il token è un operatore di visualizzazione del testo (Tj, TJ, `'`, `"`)	`bool`	Nessuno; restituisce `false` per i token non operatore	Sottoinsieme degli operatori di testo.
`ContentTokenType`	— (enum con valori string)	Enumera i discriminatori dei token: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	I valori di backing sono identificatori stabili.
`ProjectionIntent`	— (enum puro)	Enumera i due intenti di emissione consentiti: Sanitization, SteganographicEmbedding	—	—	Nessun caso generico, così l’analisi statica segnala un uso non dichiarato.

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

Contratto di comportamento

ContentProjectionWriter::tokenize($contentStream) analizza lessicalmente lo stream in una list<ContentToken> piatta e ordinata. Copre stringhe letterali, stringhe esadecimali, nomi, numeri, delimitatori di array e dizionario, valori booleani, null e operatori. Gli spazi e i commenti vengono consumati ed eliminati; un byte non riconosciuto fa avanzare il cursore senza produrre un token. Il passaggio è di sola lettura e non necessita di alcun intento.

emit($tokens, $intent) serializza una lista di token nei byte di un content stream e richiede un ProjectionIntent. L’intento è solo una dichiarazione al call site: i byte emessi sono identici indipendentemente dal caso passato. I numeri mantengono la propria distinzione tra intero e float: gli interi vengono emessi alla lettera, i float vengono emessi con un massimo di sei cifre decimali e con gli zeri finali rimossi. Le stringhe letterali vengono nuovamente sottoposte a escape, le stringhe esadecimali vengono emesse in esadecimale maiuscolo e i nomi conservano la barra iniziale. Ogni operatore è seguito da un a capo; i delimitatori di array e dizionario sopprimono il separatore adiacente.

roundTrip($contentStream) tokenizza e quindi riemette senza modifiche. È il gate di validazione: confermare un risultato pulito prima di affidarsi a una qualsiasi sequenza di modifica-ed-emissione. L’output non è identico byte per byte all’input — gli spazi vengono normalizzati e i commenti scompaiono — ma la sequenza degli operatori e i valori degli operandi sono preservati.

ProjectionIntent ha esattamente due casi: Sanitization (redazione distruttiva e irreversibile) e SteganographicEmbedding (incorporamento di payload nascosto). Non esiste alcun caso generico, così l’analisi statica può segnalare qualsiasi emissione priva di uno scopo dichiarato e noto. ContentToken è un valore immutabile readonly che porta un discriminatore type e un value decodificato; isTextOperator() e isTextShowingOperator() classificano i token operatore e restituiscono false per ogni token non operatore.

Casi limite e modalità di errore

Confermare un round-trip pulito prima di qualsiasi sequenza di modifica-ed-emissione. Trattare un round-trip fallito come una condizione di arresto.
L’intento Sanitization è irreversibile. I token rimossi sono assenti dall’output e non possono essere recuperati da esso.
L’intento non modifica l’output. emit() produce gli stessi byte per entrambi i casi; l’argomento è un gate al call site. La redazione e le modifiche steganografiche vengono applicate dal chiamante che muta la lista di token prima dell’emissione.
L’emettitore normalizza gli spazi ed elimina i commenti, pertanto il confronto a livello di byte con l’originale differisce anche per un round-trip non modificato.
Gli operandi float sono formattati con un massimo di sei cifre decimali e quindi rifiniti. I valori che necessitano di maggiore precisione vengono arrotondati all’emissione; gli interi sono esatti.
Gli escape delle stringhe letterali in input decodificati includono \n, \r, \t, \b, \f, i delimitatori sottoposti a escape e gli escape ottali fino a tre cifre limitati a un byte.
Una stringa esadecimale con un numero dispari di cifre viene completata con uno zero finale in input, conformemente alla regola ISO sulle stringhe esadecimali.
I byte malformati o di controllo vengono ignorati, non rifiutati; tokenize() non genera alcuna eccezione su input inatteso.
Questo modulo non esegue alcuna operazione crittografica e non definisce alcun comportamento specifico FIPS.

Conformità

La tokenizzazione tratta lo stream come una sequenza di operatori e operandi nella sintassi standard degli oggetti PDF, secondo ISO 32000-2:2020, 8.2. Il raggruppamento da byte a token segue le classi lessicali di caratteri di ISO 32000-2:2020, 7.2. Una stringa esadecimale di lunghezza dispari completa la cifra finale con zero, secondo ISO 32000-2:2020, 7.3.4.3. Queste clausole sono registrate nel record delle citazioni di questa pagina.

Queste affermazioni descrivono la capacità rispetto alle clausole citate. NextPDF non detiene alcuna certificazione di conformità e il supporto per una clausola non costituisce una dichiarazione di certificazione.

Note di sviluppo

Disponibile dalla release 1.10.0 del modulo; tutte e tre le operazioni sono punti di ingresso statici su ContentProjectionWriter.
Tokenize ed emit sono lineari rispetto alla lunghezza del content stream. Non esiste alcun dato di throughput pubblicato; misurare con stream rappresentativi.
Il modello di token piatto — un token per elemento lessicale, non raggruppato per operatore — è ciò che consente modifiche chirurgiche come la regolazione di un singolo numero all’interno di un array TJ. Le rappresentazioni raggruppate per operatore risiedono altrove nell’albero Pro e sono fuori dall’ambito di questa pagina.
ContentToken è immutabile. Costruire una lista modificata creando nuovi token anziché mutare quelli esistenti.
Mantenere il gate di round-trip nella propria pipeline: un roundTrip() superato è la precondizione attorno alla quale il modulo è progettato prima di qualsiasi modifica distruttiva.

Confine di pubblicazione

Questa pagina documenta esclusivamente il comportamento osservabile esternamente e la superficie API pubblica supportata. I percorsi di namespace interni, le classi di supporto, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.