Pro editie

Projection — Diepe referentie

In het kort

Deze pagina is de diepe referentie voor de Pro Projection-module. Ze documenteert het openbare tokenize-, emit- en round-trip-oppervlak, de intent-gate en de round-trip-semantiek van contentstreams. ContentProjectionWriter leest een PDF-contentstream in als een platte, geordende tokenlijst en serialiseert een tokenlijst vervolgens opnieuw tot een nieuwe contentstream. Het model is eenrichting: emissie produceert een nieuwe stream, nooit een in-place bewerking van het origineel.

Let op. “Projection” betekent hier content-stream-tokenprojectie, niet coördinaten- of geospatiale projectie.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelope op Pro-niveau. Een deployment zonder die rechten laadt de klassen van de functionaliteit niet. Vergelijk edities en vraag een licentie aan.

Er bestaat geen licentievlag per feature. Dit is een functionaliteit van de Pro-editie. Emissie vereist daarnaast een expliciet ProjectionIntent-argument dat door het typesysteem wordt afgedwongen, niet door een licentieschakelaar.

Publiek API-oppervlak

composer require nextpdf/pro:^3

De module leeft in de namespace NextPDF\Pro\Projection. Alle operaties op ContentProjectionWriter zijn static.

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`ContentProjectionWriter::tokenize`	`string $contentStream`	Leest de stream in als een platte, geordende tokenlijst; normaliseert whitespace, laat comments weg, slaat niet-herkende bytes over	`list<ContentToken>`	Geen; misvormde of controlebytes worden overgeslagen, niet afgewezen	Alleen-lezen; vereist geen intent.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	Serialiseert tokens tot een nieuwe contentstream; de uitvoer is onafhankelijk van de intent-waarde	`string`	Geen in de body; een ontbrekend of niet-`ProjectionIntent`-argument faalt op de typegrens	Intent is een call-site-gate, geen runtime-schakelaar.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	Tokeniseert en re-emitteert vervolgens zonder wijziging; de validatie-gate	`string`	Geen	De uitvoer is niet byte-identiek; de operatorvolgorde en operandwaarden blijven behouden.
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	Bouwt een immutable token; voert geen validatie uit	`ContentToken`	Geen; een type-incompatibele `$value` faalt op de typegrens	`readonly`; `type` en `value` zijn public.
`ContentToken::isTextOperator`	—	Geeft aan of het token een tekstoperator is (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, `'`, `"`)	`bool`	Geen; retourneert `false` voor niet-operatortokens	—
`ContentToken::isTextShowingOperator`	—	Geeft aan of het token een text-showing-operator is (Tj, TJ, `'`, `"`)	`bool`	Geen; retourneert `false` voor niet-operatortokens	Subset van de tekstoperatoren.
`ContentTokenType`	— (string-backed enum)	Somt tokendiscriminatoren op: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	Backing-waarden zijn stabiele identifiers.
`ProjectionIntent`	— (pure enum)	Somt de twee toegestane emissie-intents op: Sanitization, SteganographicEmbedding	—	—	Geen generiek geval, dus statische analyse markeert niet-gedeclareerd gebruik.

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

Gedragscontract

ContentProjectionWriter::tokenize($contentStream) leest de stream in als een platte, geordende list<ContentToken>. Ze dekt literal strings, hex strings, names, getallen, array- en dictionarydelimiters, booleans, null en operatoren. Whitespace en comments worden geconsumeerd en weggelaten; een niet-herkende byte verplaatst de cursor zonder een token te produceren. De pass is alleen-lezen en heeft geen intent nodig.

emit($tokens, $intent) serialiseert een tokenlijst terug naar content-stream-bytes en vereist een ProjectionIntent. De intent is uitsluitend een declaratie op de call-site: de uitgevoerde bytes zijn identiek, ongeacht welk geval wordt doorgegeven. Getallen behouden hun integer/float-onderscheid — integers worden verbatim uitgevoerd, floats met maximaal zes decimalen en met afgekapte nullen aan het einde. Literal strings worden opnieuw ge-escaped, hex strings worden als hoofdletter-hex uitgevoerd, en names dragen hun voorafgaande solidus. Elke operator wordt gevolgd door een newline; array- en dictionarydelimiters onderdrukken de aangrenzende separator.

roundTrip($contentStream) tokeniseert en re-emitteert vervolgens zonder wijziging. Het is de validatie-gate: bevestig een schoon resultaat voordat je enige modify-and-emit-sequentie vertrouwt. De uitvoer is niet byte-identiek aan de invoer — whitespace wordt genormaliseerd en comments zijn weg — maar de operatorvolgorde en operandwaarden blijven behouden.

ProjectionIntent heeft precies twee gevallen: Sanitization (destructieve, onomkeerbare redaction) en SteganographicEmbedding (verborgen payload-embedding). Er is geen generiek geval, dus statische analyse kan elke emissie markeren die geen gedeclareerd, bekend doel heeft. ContentToken is een immutable readonly-waarde met een type-discriminator en een gedecodeerde value; isTextOperator() en isTextShowingOperator() classificeren operatortokens en retourneren false voor elk niet-operatortoken.

Randgevallen en faalmodi

Bevestig een schone round-trip vóór elke modify-and-emit-sequentie. Behandel een mislukte round-trip als een stopconditie.
De Sanitization-intent is onomkeerbaar. Verwijderde tokens ontbreken in de uitvoer en kunnen er niet uit worden hersteld.
Intent verandert de uitvoer niet. emit() produceert voor beide gevallen dezelfde bytes; het argument is een call-site-gate. Redaction en steganografische bewerkingen worden toegepast doordat de aanroeper de tokenlijst muteert vóór de emissie.
De emitter normaliseert whitespace en laat comments weg, dus een bytevergelijking met het origineel verschilt zelfs bij een ongewijzigde round-trip.
Float-operanden worden geformatteerd met maximaal zes decimalen en vervolgens afgekapt. Waarden die meer precisie vereisen, worden bij emissie afgerond; integers zijn exact.
Gedecodeerde literal-string-escapes in de invoer omvatten \n, \r, \t, \b, \f, ge-escapete delimiters en octale escapes van maximaal drie cijfers, geklemd op één byte.
Een hex string met een oneven aantal cijfers wordt bij de invoer aangevuld met een nul aan het einde, conform de ISO-hexadecimalestringregel.
Misvormde of controlebytes worden overgeslagen, niet afgewezen; tokenize() gooit geen exception bij onverwachte invoer.
Deze module voert geen cryptografische bewerkingen uit en definieert geen FIPS-specifiek gedrag.

Conformiteit

Tokenisatie behandelt de stream als een reeks operatoren en operanden in standaard PDF-objectsyntaxis, conform ISO 32000-2:2020, 8.2. De groepering van bytes tot tokens volgt de lexicale tekenklassen van ISO 32000-2:2020, 7.2. Een hex string met een oneven lengte vult het laatste cijfer aan als nul, conform ISO 32000-2:2020, 7.3.4.3. Deze clausules zijn vastgelegd in het citation-record van deze pagina.

Deze uitspraken beschrijven de functionaliteit ten opzichte van de geciteerde clausules. NextPDF beschikt over geen conformiteitscertificering, en ondersteuning voor een clausule is geen certificeringsclaim.

Ontwikkelnotities

Beschikbaar sinds de 1.10.0-release van de module; alle drie de operaties zijn static entry points op ContentProjectionWriter.
Tokenize en emit zijn lineair in de lengte van de contentstream. Er is geen gepubliceerd doorvoercijfer; meet met representatieve streams.
Het platte tokenmodel — één token per lexicaal element, niet gegroepeerd per operator — is wat chirurgische bewerkingen mogelijk maakt, zoals het aanpassen van één enkel getal binnen een TJ-array. Per operator gegroepeerde representaties leven elders in de Pro-tree en vallen hier buiten scope.
ContentToken is immutable. Bouw een gewijzigde lijst door nieuwe tokens te construeren in plaats van bestaande te muteren.
Houd de round-trip-gate in je pipeline: een geslaagde roundTrip() is de voorwaarde waaromheen de module is ontworpen, vóór elke destructieve bewerking.

Publicatiegrens

Deze pagina documenteert uitsluitend extern waarneembaar gedrag en het ondersteunde openbare API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten scope.