Pro Edition

Projection — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Detailreferenz für das Pro-Modul Projection. Sie dokumentiert die öffentliche tokenize-, emit- und round-trip-Oberfläche, das Intent-Gate und die Round-Trip-Semantik von Content-Streams. ContentProjectionWriter zerlegt einen PDF-Content-Stream lexikalisch in eine flache, geordnete Token-Liste und serialisiert eine Token-Liste anschließend erneut in einen neuen Content-Stream. Das Modell ist einseitig (one-way): Die Emission erzeugt einen neuen Stream, niemals eine In-place-Bearbeitung des Originals.

Hinweis. „Projection” bezeichnet hier die Token-Projektion von Content-Streams, nicht eine Koordinaten- oder Geodatenprojektion.

Verfügbarkeit & Lizenzierung

Diese Funktion ist Bestandteil von NextPDF Pro (nextpdf/pro) und wird mit einer Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Es gibt kein Lizenz-Flag je Funktion. Dies ist eine Funktion der Pro-Edition. Die Emission erfordert zusätzlich ein explizites ProjectionIntent-Argument, das vom Typsystem erzwungen wird, kein Lizenzschalter.

Öffentliche API-Oberfläche

composer require nextpdf/pro:^3

Das Modul befindet sich im Namespace NextPDF\Pro\Projection. Alle Operationen auf ContentProjectionWriter sind statisch.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`ContentProjectionWriter::tokenize`	`string $contentStream`	Zerlegt den Stream lexikalisch in eine flache, geordnete Token-Liste; normalisiert Leerraum, verwirft Kommentare, überspringt unerkannte Bytes	`list<ContentToken>`	Keine; fehlerhafte oder Steuer-Bytes werden übersprungen, nicht abgelehnt	Schreibgeschützt; erfordert kein Intent.
`ContentProjectionWriter::emit`	`list<ContentToken> $tokens`, `ProjectionIntent $intent`	Serialisiert Token in einen neuen Content-Stream; die Ausgabe ist unabhängig vom Intent-Wert	`string`	Keine im Rumpf; ein fehlendes oder nicht-`ProjectionIntent`-Argument scheitert an der Typgrenze	Intent ist ein Gate an der Aufrufstelle, kein Laufzeitschalter.
`ContentProjectionWriter::roundTrip`	`string $contentStream`	Tokenisiert und emittiert anschließend ohne Änderung erneut; das Validierungs-Gate	`string`	Keine	Die Ausgabe ist nicht byte-identisch; Operatorreihenfolge und Operandenwerte bleiben erhalten.
`ContentToken::__construct`	`ContentTokenType $type`, `string\|int\|float\|bool\|null $value = null`	Erzeugt ein unveränderliches Token; führt keine Validierung durch	`ContentToken`	Keine; ein typinkompatibler `$value` scheitert an der Typgrenze	`readonly`; `type` und `value` sind public.
`ContentToken::isTextOperator`	—	Gibt an, ob das Token ein Textoperator ist (BT, ET, Tj, TJ, Td, TD, Tm, T*, Tf, Tc, Tw, Tz, TL, Tr, Ts, `'`, `"`)	`bool`	Keine; gibt `false` für Nicht-Operator-Token zurück	—
`ContentToken::isTextShowingOperator`	—	Gibt an, ob das Token ein Text-anzeigender Operator ist (Tj, TJ, `'`, `"`)	`bool`	Keine; gibt `false` für Nicht-Operator-Token zurück	Teilmenge der Textoperatoren.
`ContentTokenType`	— (string-backed enum)	Zählt die Token-Diskriminatoren auf: LiteralString, HexString, Number, Name, Operator, ArrayBegin, ArrayEnd, DictBegin, DictEnd, Boolean, Null	—	—	Die Backing-Werte sind stabile Bezeichner.
`ProjectionIntent`	— (pure enum)	Zählt die beiden zulässigen Emissions-Intents auf: Sanitization, SteganographicEmbedding	—	—	Kein generischer Fall, daher meldet die statische Analyse undeklarierte Verwendung.

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

Verhaltensvertrag

ContentProjectionWriter::tokenize($contentStream) zerlegt den Stream lexikalisch in eine flache, geordnete list<ContentToken>. Er erfasst literale Strings, Hex-Strings, Namen, Zahlen, Array- und Dictionary-Trennzeichen, Booleans, Null und Operatoren. Leerraum und Kommentare werden verbraucht und verworfen; ein unerkanntes Byte rückt den Cursor vor, ohne ein Token zu erzeugen. Der Durchlauf ist schreibgeschützt und benötigt kein Intent.

emit($tokens, $intent) serialisiert eine Token-Liste zurück in Content-Stream-Bytes und erfordert ein ProjectionIntent. Das Intent ist ausschließlich eine Deklaration an der Aufrufstelle: Die emittierten Bytes sind identisch, unabhängig davon, welcher Fall übergeben wird. Zahlen behalten ihre Unterscheidung zwischen Ganzzahl und Gleitkomma bei — Ganzzahlen werden wortgetreu emittiert, Gleitkommazahlen mit bis zu sechs Nachkommastellen und abgeschnittenen nachlaufenden Nullen. Literale Strings werden neu escaped, Hex-Strings als Großbuchstaben-Hex emittiert, und Namen tragen ihren führenden Solidus. Auf jeden Operator folgt ein Zeilenumbruch; Array- und Dictionary-Trennzeichen unterdrücken das angrenzende Trennzeichen.

roundTrip($contentStream) tokenisiert und emittiert anschließend ohne Änderung erneut. Es ist das Validierungs-Gate: Bestätigen Sie ein sauberes Ergebnis, bevor Sie einer Modify-and-Emit-Sequenz vertrauen. Die Ausgabe ist nicht byte-identisch zur Eingabe — Leerraum wird normalisiert und Kommentare entfallen —, aber die Operatorreihenfolge und die Operandenwerte bleiben erhalten.

ProjectionIntent hat genau zwei Fälle: Sanitization (destruktive, irreversible Redaction) und SteganographicEmbedding (Einbettung verborgener Payloads). Es gibt keinen generischen Fall, sodass die statische Analyse jede Emission melden kann, der ein deklarierter, bekannter Zweck fehlt. ContentToken ist ein unveränderlicher readonly-Wert mit einem type-Diskriminator und einem dekodierten value; isTextOperator() und isTextShowingOperator() klassifizieren Operator-Token und geben für jedes Nicht-Operator-Token false zurück.

Grenzfälle & Fehlermodi

Bestätigen Sie einen sauberen Round-Trip vor jeder Modify-and-Emit-Sequenz. Behandeln Sie einen fehlgeschlagenen Round-Trip als Abbruchbedingung.
Das Sanitization-Intent ist irreversibel. Entfernte Token fehlen in der Ausgabe und können nicht aus ihr wiederhergestellt werden.
Das Intent ändert die Ausgabe nicht. emit() erzeugt für beide Fälle dieselben Bytes; das Argument ist ein Gate an der Aufrufstelle. Redaction- und steganografische Änderungen werden vom Aufrufer angewendet, der die Token-Liste vor der Emission mutiert.
Der Emitter normalisiert Leerraum und verwirft Kommentare, sodass ein Byte-Vergleich mit dem Original selbst bei einem unveränderten Round-Trip abweicht.
Gleitkomma-Operanden werden mit höchstens sechs Nachkommastellen formatiert und dann gekürzt. Werte, die mehr Präzision benötigen, werden bei der Emission gerundet; Ganzzahlen sind exakt.
Zu den dekodierten Escapes literaler Eingabe-Strings gehören \n, \r, \t, \b, \f, escapte Trennzeichen sowie bis zu dreistellige Oktal-Escapes, auf ein Byte begrenzt.
Ein Hex-String mit ungerader Ziffernanzahl wird bei der Eingabe mit einer nachlaufenden Null aufgefüllt, entsprechend der ISO-Regel für Hexadezimal-Strings.
Fehlerhafte oder Steuer-Bytes werden übersprungen, nicht abgelehnt; tokenize() wirft bei unerwarteter Eingabe keine Ausnahme.
Dieses Modul führt keine kryptografischen Operationen durch und definiert kein FIPS-spezifisches Verhalten.

Konformität

Die Tokenisierung behandelt den Stream als Folge von Operatoren und Operanden in der Standard-PDF-Objektsyntax, gemäß ISO 32000-2:2020, 8.2. Die Gruppierung von Bytes zu Token folgt den lexikalischen Zeichenklassen von ISO 32000-2:2020, 7.2. Ein Hex-String ungerader Länge füllt die letzte Ziffer mit Null auf, gemäß ISO 32000-2:2020, 7.3.4.3. Diese Klauseln sind im Zitationsdatensatz dieser Seite festgehalten.

Diese Aussagen beschreiben die Funktionalität in Bezug auf die zitierten Klauseln. NextPDF besitzt keine Konformitätszertifizierung, und die Unterstützung einer Klausel ist keine Zertifizierungsaussage.

Entwicklungshinweise

Verfügbar seit dem 1.10.0-Release des Moduls; alle drei Operationen sind statische Einstiegspunkte auf ContentProjectionWriter.
Tokenize und emit sind linear zur Content-Stream-Länge. Es gibt keine veröffentlichte Durchsatzangabe; messen Sie mit repräsentativen Streams.
Das flache Token-Modell — ein Token pro lexikalischem Element, nicht operatorgruppiert — ermöglicht chirurgische Änderungen wie das Anpassen einer einzelnen Zahl innerhalb eines TJ-Arrays. Operatorgruppierte Darstellungen befinden sich an anderer Stelle im Pro-Baum und sind hier nicht im Umfang.
ContentToken ist unveränderlich. Erstellen Sie eine geänderte Liste, indem Sie neue Token konstruieren, statt bestehende zu mutieren.
Behalten Sie das Round-Trip-Gate in Ihrer Pipeline: Ein bestandenes roundTrip() ist die Vorbedingung, um die das Modul vor jeder destruktiven Änderung konzipiert ist.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe sind nicht im Umfang.