Pro édition

Projection — Référence détaillée

En bref

Cette page est la référence détaillée du module Projection de Pro. Elle documente la surface publique de tokenisation, d’émission et d’aller-retour, la barrière d’intention et la sémantique d’aller-retour des flux de contenu. ContentProjectionWriter analyse lexicalement un flux de contenu PDF en une liste de tokens plate et ordonnée, puis re-sérialise une liste de tokens en un nouveau flux de contenu. Le modèle est unidirectionnel : l’émission produit un nouveau flux, jamais une modification en place de l’original.

Note. Ici, « Projection » désigne la projection de tokens de flux de contenu, et non une projection de coordonnées ou géospatiale.

Disponibilité et licence

Cette fonctionnalité est livrée dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la fonctionnalité. Compare les éditions et obtiens une licence.

Il n’existe aucun indicateur de licence par fonctionnalité. Il s’agit d’une fonctionnalité de l’édition Pro. L’émission exige en outre un argument ProjectionIntent explicite, imposé par le système de types et non par un interrupteur de licence.

Surface d’API publique

composer require nextpdf/pro:^3

Le module réside dans l’espace de noms NextPDF\Pro\Projection. Toutes les opérations de ContentProjectionWriter sont statiques.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`ContentProjectionWriter::tokenize`	`string $contentStream`	Analyse lexicalement le flux en une liste de tokens plate et ordonnée ; normalise les espaces, supprime les commentaires, ignore les octets non reconnus	`list<ContentToken>`	Aucun ; les octets malformés ou de contrôle sont ignorés, pas rejetés	Lecture seule ; ne nécessite aucune intention.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	Sérialise les tokens en un nouveau flux de contenu ; la sortie est indépendante de la valeur d’intention	`string`	Aucun dans le corps ; un argument absent ou non-`ProjectionIntent` échoue à la frontière de types	L’intention est une barrière au site d’appel, pas un interrupteur d’exécution.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	Tokenise puis ré-émet sans modification ; la barrière de validation	`string`	Aucun	La sortie n’est pas identique octet pour octet ; la séquence d’opérateurs et les valeurs d’opérandes sont préservées.
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	Construit un token immuable ; n’effectue aucune validation	`ContentToken`	Aucun ; une valeur `$value` incompatible en type échoue à la frontière de types	`readonly` ; `type` et `value` sont publics.
`ContentToken::isTextOperator`	—	Indique si le token est un opérateur de texte (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, `'`, `"`)	`bool`	Aucun ; retourne `false` pour les tokens non-opérateurs	—
`ContentToken::isTextShowingOperator`	—	Indique si le token est un opérateur d’affichage de texte (Tj, TJ, `'`, `"`)	`bool`	Aucun ; retourne `false` pour les tokens non-opérateurs	Sous-ensemble des opérateurs de texte.
`ContentTokenType`	— (enum à valeurs chaîne)	Énumère les discriminants de token : LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	Les valeurs de support sont des identifiants stables.
`ProjectionIntent`	— (enum pur)	Énumère les deux intentions d’émission autorisées : Sanitization, SteganographicEmbedding	—	—	Aucun cas générique, de sorte que l’analyse statique signale toute utilisation non déclarée.

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

Contrat de comportement

ContentProjectionWriter::tokenize($contentStream) analyse lexicalement le flux en une list<ContentToken> plate et ordonnée. Elle couvre les chaînes littérales, les chaînes hexadécimales, les noms, les nombres, les délimiteurs de tableau et de dictionnaire, les booléens, null et les opérateurs. Les espaces et les commentaires sont consommés et supprimés ; un octet non reconnu avance le curseur sans produire de token. La passe est en lecture seule et ne nécessite aucune intention.

emit($tokens, $intent) sérialise une liste de tokens en octets de flux de contenu et exige un ProjectionIntent. L’intention est une simple déclaration au site d’appel : les octets émis sont identiques quel que soit le cas transmis. Les nombres conservent leur distinction entier/flottant — les entiers sont émis tels quels, les flottants sont émis avec au plus six chiffres après la virgule, les zéros de fin étant supprimés. Les chaînes littérales sont ré-échappées, les chaînes hexadécimales sont émises en hexadécimal majuscule et les noms portent leur barre oblique initiale. Chaque opérateur est suivi d’un saut de ligne ; les délimiteurs de tableau et de dictionnaire suppriment le séparateur adjacent.

roundTrip($contentStream) tokenise puis ré-émet sans changement. C’est la barrière de validation : confirme un résultat propre avant de te fier à toute séquence de modification puis d’émission. La sortie n’est pas identique octet pour octet à l’entrée — les espaces sont normalisés et les commentaires ont disparu — mais la séquence d’opérateurs et les valeurs d’opérandes sont préservées.

ProjectionIntent a exactement deux cas : Sanitization (rédaction destructrice et irréversible) et SteganographicEmbedding (intégration d’une charge utile cachée). Il n’existe aucun cas générique, de sorte que l’analyse statique peut signaler toute émission dépourvue d’un but déclaré et connu. ContentToken est une valeur immuable readonly portant un discriminant type et une value décodée ; isTextOperator() et isTextShowingOperator() classent les tokens opérateurs et retournent false pour tout token non-opérateur.

Cas limites et modes de défaillance

Confirme un aller-retour propre avant toute séquence de modification puis d’émission. Considère un aller-retour en échec comme une condition d’arrêt.
L’intention Sanitization est irréversible. Les tokens supprimés sont absents de la sortie et ne peuvent en être récupérés.
L’intention ne change pas la sortie. emit() produit les mêmes octets pour l’un ou l’autre cas ; l’argument est une barrière au site d’appel. La rédaction et les modifications stéganographiques sont appliquées par l’appelant qui mute la liste de tokens avant l’émission.
L’émetteur normalise les espaces et supprime les commentaires, de sorte que la comparaison au niveau des octets avec l’original diffère même pour un aller-retour non modifié.
Les opérandes flottants sont formatés avec au plus six chiffres après la virgule, puis rognés. Les valeurs nécessitant plus de précision sont arrondies à l’émission ; les entiers sont exacts.
Les échappements de chaîne littérale décodés en entrée incluent \n, \r, \t, \b, \f, les délimiteurs échappés et les échappements octaux d’au plus trois chiffres bornés à un octet.
Une chaîne hexadécimale comportant un nombre impair de chiffres est complétée par un zéro final en entrée, conformément à la règle ISO sur les chaînes hexadécimales.
Les octets malformés ou de contrôle sont ignorés, pas rejetés ; tokenize() ne lève aucune exception sur une entrée inattendue.
Ce module n’effectue aucune opération cryptographique et ne définit aucun comportement spécifique à FIPS.

Conformité

La tokenisation traite le flux comme une séquence d’opérateurs et d’opérandes dans la syntaxe d’objet PDF standard, selon ISO 32000-2:2020, 8.2. Le regroupement des octets en tokens suit les classes lexicales de caractères d’ISO 32000-2:2020, 7.2. Une chaîne hexadécimale de longueur impaire complète le dernier chiffre par un zéro, selon ISO 32000-2:2020, 7.3.4.3. Ces articles sont consignés dans le registre de citations de cette page.

Ces énoncés décrivent la capacité au regard des articles cités. NextPDF ne détient aucune certification de conformité, et la prise en charge d’un article ne constitue pas une affirmation de certification.

Notes de développement

Disponible depuis la version 1.10.0 du module ; les trois opérations sont des points d’entrée statiques de ContentProjectionWriter.
Tokenize et emit sont linéaires par rapport à la longueur du flux de contenu. Aucun chiffre de débit n’est publié ; mesure avec des flux représentatifs.
Le modèle de tokens plat — un token par élément lexical, non regroupé par opérateur — est ce qui permet des modifications chirurgicales telles que l’ajustement d’un seul nombre à l’intérieur d’un tableau TJ. Les représentations regroupées par opérateur se trouvent ailleurs dans l’arborescence Pro et sortent du périmètre de cette page.
ContentToken est immuable. Construis une liste modifiée en créant de nouveaux tokens plutôt qu’en mutant les tokens existants.
Conserve la barrière d’aller-retour dans ton pipeline : un roundTrip() réussi est la précondition autour de laquelle le module est conçu, avant toute modification destructrice.

Périmètre de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sortent du périmètre.