Pro Edition

Projection

Auf einen Blick

Projection parst einen PDF-Content-Stream in eine flache Token-Liste und gibt aus diesen Tokens einen neuen Content-Stream aus. Die Ausgabe erfordert eine explizit deklarierte Absicht. Dieses Modul ist kein PDF-Editor für allgemeine Zwecke.

Hinweis. „Projection“ bedeutet hier eine Content-Stream-Token-Projektion. Es handelt sich nicht um eine Koordinaten- oder Geo-Projektion. Für Geo-Funktionen siehe das Geo-Modul.

Verfügbarkeit & Lizenzierung

Diese Funktion wird in NextPDF Pro (nextpdf/pro) ausgeliefert und wird mit einer Lizenzhülle der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Es gibt kein separates Lizenz-Flag pro Funktion. Ein erforderliches ProjectionIntent-Argument gatet die Ausgabe auf API-Ebene, kein Lizenzschalter.

Installation

composer require nextpdf/pro:^3

Der Code befindet sich im Namespace NextPDF\Pro\Projection.

Konzeptioneller Überblick

ContentProjectionWriter stellt drei statische Operationen bereit:

tokenize() parst einen Content-Stream in eine flache, geordnete Token-Liste. Dies ist schreibgeschützt und benötigt keine Absicht.
emit() schreibt aus einer (möglicherweise veränderten) Token-Liste einen neuen Content-Stream. Es erfordert eine ProjectionIntent.
roundTrip() tokenisiert und gibt anschließend ohne Änderungen erneut aus, zur Validierung.

Die Ausgabe ist konzeptionell ein neuer Content-Stream, keine bearbeitete Kopie des Originals. Der Emitter normalisiert Leerraum und Kommentare, hält die Operatorsequenz und die Operandenwerte jedoch exakt. Das Intent-Enum hat genau zwei Fälle — Bereinigung (Schwärzung) und steganografische Einbettung — und hat bewusst keinen generischen Fall, sodass die statische Analyse unbeabsichtigte Verwendung erkennen kann.

Warum es so funktioniert

Projection weigert sich, ein PDF-Editor für allgemeine Zwecke zu sein. Die Ausgabe baut aus einer flachen Token-Liste einen frischen Content-Stream neu auf, sodass das Original niemals an Ort und Stelle verändert wird. Dieses einseitige Modell macht die Schwärzung vertrauenswürdig: entfernte Tokens sind in der Ausgabe abwesend, nicht übermalt. emit() verlangt daher eine explizite ProjectionIntent, und das Enum bietet nur Bereinigung und steganografische Einbettung — keinen generischen Fall. Die statische Analyse kann dann jede Ausgabe kennzeichnen, der ein deklarierter, bekannter Zweck fehlt. Der Entwurf tauscht Bearbeitungskomfort gegen die Garantie, dass destruktive Absicht an der Aufrufstelle stets sichtbar ist.

Entwurfshintergrund: Schwärzung ist kein schwarzes Rechteck.

Verhaltensvertrag

tokenize($contentStream) gibt eine Liste von Tokens zurück, die Strings, Namen, Zahlen, Arrays, Dictionaries, Booleans, null und Operatoren abdeckt.
emit($tokens, $intent) erfordert eine explizite Absicht; das Typsystem erzwingt dies an der Aufrufstelle.
Die roundTrip()-Ausgabe ist nicht byte-identisch zur Eingabe, aber die Operatorsequenz und die Operandenwerte stimmen überein.
Der Emitter formatiert Zahlen so, dass die Unterscheidung zwischen Ganzzahl und Float erhalten bleibt, und escaped literale Strings erneut.
Die beiden deklarierten Absichten sind Bereinigung (eine destruktive, unwiderrufliche Schwärzungsoperation) und steganografische Einbettung.

Codebeispiel — Schnellstart

Das Folgende spiegelt die dokumentierte öffentliche API wider. Das Repository liefert für dieses Modul kein ausführbares Beispiel aus.

use NextPDF\Pro\Projection\ContentProjectionWriter;

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

Codebeispiel — Produktion

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

Randfälle & Fallstricke

Führen Sie roundTrip() aus und bestätigen Sie, dass er hält, bevor Sie einer Modify-and-Emit-Sequenz vertrauen. Behandeln Sie einen fehlschlagenden Round-Trip als Stopp-Bedingung.
Die Bereinigungsabsicht ist unwiderruflich. Entfernter Inhalt kann aus der Ausgabe nicht wiederhergestellt werden.
Der Emitter normalisiert Leerraum und verwirft Kommentare, sodass ein Byte-Level-Vergleich mit dem Original selbst bei einem unveränderten Round-Trip abweicht.

Performance

Tokenize und Emit sind linear in der Länge des Content-Streams. Der Tokenizer begrenzt das Lesen oktaler Escapes und die Behandlung von Hex-Strings. Es gibt keine veröffentlichte Durchsatzzahl. Messen Sie mit repräsentativen Content-Streams.

Sicherheitshinweise

Das erforderliche Intent-Argument verhindert den Missbrauch als allgemeiner Editor. Die Bereinigungsabsicht ist destruktiv und unwiderruflich; verifizieren Sie zuerst den Round-Trip und bestätigen Sie die geschwärzte Ausgabe vor der Verteilung. Dieses Modul protokolliert keinen Inhalt.

Konformität

Die Tokenisierung folgt den lexikalischen und Content-Stream-Konventionen in ISO 32000-2; die Quelle annotiert die relevanten Klauseln. Der RAG-Korpus war zum Zeitpunkt der Erstellung nicht verfügbar, sodass diese Seite keine externen Klausel-Identifikatoren behauptet und Konformitätsaussagen auf das durch die Tests des Moduls verifizierte Verhalten beschränkt.

Hinweis zur Enterprise-Grenze

Enterprise ändert das Verhalten von Projection nicht. Enterprise ergänzt höherstufige Privacy- und Compliance-Funktionen, die separat dokumentiert sind; sie sind nicht erforderlich, um die Projection-API zu nutzen.

Core-Fallback / Alternative

Es gibt kein Core-Äquivalent. Ohne Pro müssen Aufrufer ihren eigenen Content-Stream-Tokenizer bauen; das intent-gated Projektionsmodell ist eine ausschließlich in Pro verfügbare Ergänzung.

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 liegen außerhalb des Geltungsbereichs.