Pro editie

Projection

In het kort

Projection parseert een PDF-content-stream tot een platte tokenlijst en genereert een nieuwe content-stream uit die tokens. Generatie vereist een expliciet gedeclareerde intentie. Deze module is geen algemene PDF-editor.

Opmerking. “Projection” betekent hier content-stream-tokenprojectie. Het is geen coördinaat- of geospatiale projectie. Voor geospatiale functies, zie de Geo-module.

Beschikbaarheid en licentie

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

Er is geen aparte per-feature licentie-flag. Een vereist ProjectionIntent-argument bewaakt de generatie op API-niveau, niet een licentie-switch.

Installatie

composer require nextpdf/pro:^3

De code bevindt zich onder de namespace NextPDF\Pro\Projection.

Conceptueel overzicht

ContentProjectionWriter biedt drie statische bewerkingen:

tokenize() parseert een content-stream tot een platte, geordende tokenlijst. Dit is alleen-lezen en vereist geen intentie.
emit() schrijft een nieuwe content-stream uit een (mogelijk gewijzigde) tokenlijst. Het vereist een ProjectionIntent.
roundTrip() tokeniseert en genereert vervolgens opnieuw zonder wijzigingen, ter validatie.

De uitvoer is conceptueel een nieuwe content-stream, geen bewerkte kopie van het origineel. De emitter normaliseert whitespace en comments, maar houdt de operatorvolgorde en operandwaarden exact. De intentie-enum heeft precies twee gevallen — sanitization (redactie) en steganografische inbedding — en heeft bewust geen generiek geval, zodat statische analyse onbedoeld gebruik kan detecteren.

Waarom het zo werkt

Projection weigert een algemene PDF-editor te zijn. Generatie bouwt een verse content-stream opnieuw op uit een platte tokenlijst, dus het origineel wordt nooit ter plekke gemuteerd. Dat eenwegmodel is wat redactie betrouwbaar maakt: verwijderde tokens zijn afwezig uit de uitvoer, niet overheen geschilderd. emit() eist daarom een expliciete ProjectionIntent, en de enum biedt alleen sanitization en steganografische inbedding — geen generiek geval. Statische analyse kan vervolgens elke generatie markeren die geen gedeclareerd, bekend doel heeft. Het ontwerp ruilt bewerkingsgemak in voor een garantie dat destructieve intentie altijd zichtbaar is op de aanroepplek.

Ontwerpachtergrond: Redactie is geen zwarte rechthoek.

Gedragscontract

tokenize($contentStream) retourneert een lijst van tokens die strings, namen, getallen, arrays, dictionaries, booleans, null en operatoren dekken.
emit($tokens, $intent) vereist een expliciete intentie; het typesysteem dwingt dit af op de aanroepplek.
De uitvoer van roundTrip() is niet byte-identiek aan de invoer, maar de operatorvolgorde en operandwaarden komen overeen.
De emitter formatteert getallen om het onderscheid tussen integer en float te behouden en escapet literal strings opnieuw.
De twee gedeclareerde intenties zijn sanitization (een destructieve, onomkeerbare redactiebewerking) en steganografische inbedding.

Codevoorbeeld — Snelstart

Het volgende weerspiegelt de gedocumenteerde publieke API. De repository levert geen uitvoerbaar voorbeeld voor deze module.

use NextPDF\Pro\Projection\ContentProjectionWriter;

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

Codevoorbeeld — Productie

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

Randgevallen en valkuilen

Draai roundTrip() en bevestig dat het standhoudt voordat je een modify-and-emit-sequentie vertrouwt. Behandel een falende round-trip als een stopconditie.
De sanitization-intentie is onomkeerbaar. Verwijderde inhoud kan niet uit de uitvoer worden hersteld.
De emitter normaliseert whitespace en laat comments vallen, dus een byte-niveauvergelijking met het origineel zal verschillen, zelfs voor een ongewijzigde round-trip.

Prestaties

Tokenize en emit zijn lineair in de lengte van de content-stream. De tokenizer begrenst octale escape-reads en hex-string-verwerking. Er is geen gepubliceerd doorvoercijfer. Meet met representatieve content-streams.

Beveiligingsnotities

Het vereiste intentie-argument voorkomt misbruik als een algemene editor. De sanitization-intentie is destructief en onomkeerbaar; verifieer eerst de round-trip en bevestig de geredigeerde uitvoer voordat je deze distribueert. Deze module logt geen inhoud.

Conformiteit

Tokenisatie volgt de lexicale en content-stream-conventies in ISO 32000-2; de bron annoteert de relevante clausules. Het RAG-corpus was tijdens het auteuren niet beschikbaar, dus deze pagina claimt geen externe clausule-identifiers en beperkt conformiteitsverklaringen tot gedrag dat door de tests van de module is geverifieerd.

Enterprise-grensnotitie

Enterprise verandert het Projection-gedrag niet. Enterprise voegt hogere privacy- en compliancefuncties toe die afzonderlijk zijn gedocumenteerd; ze zijn niet vereist om de projection-API te gebruiken.

Core-fallback / alternatief

Er is geen Core-equivalent. Zonder Pro moeten callers hun eigen content-stream-tokenizer bouwen; het intent-gated projection-model is een Pro-only-toevoeging.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.