Pro edycja

Projection

W skrócie

Projection parsuje strumień zawartości PDF na płaską listę tokenów i emituje z tych tokenów nowy strumień zawartości. Emisja wymaga jawnie zadeklarowanej intencji. Ten moduł nie jest edytorem PDF ogólnego przeznaczenia.

Uwaga. „Projection” oznacza tu projekcję tokenów strumienia zawartości. Nie jest to projekcja współrzędnych ani geoprzestrzenna. W zakresie funkcji geoprzestrzennych zobacz moduł Geo.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną warstwy Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Nie ma oddzielnej flagi licencyjnej dla poszczególnych funkcji. Wymagany argument ProjectionIntent bramkuje emisję na poziomie API, a nie przez przełącznik licencyjny.

Instalacja

composer require nextpdf/pro:^3

Kod znajduje się w przestrzeni nazw NextPDF\Pro\Projection.

Przegląd koncepcyjny

ContentProjectionWriter udostępnia trzy operacje statyczne:

tokenize() parsuje strumień zawartości na płaską, uporządkowaną listę tokenów. Jest to operacja tylko do odczytu i nie wymaga intencji.
emit() zapisuje nowy strumień zawartości z (ewentualnie zmodyfikowanej) listy tokenów. Wymaga ProjectionIntent.
roundTrip() tokenizuje, a następnie ponownie emituje bez zmian, na potrzeby walidacji.

Wynik jest koncepcyjnie nowym strumieniem zawartości, a nie edytowaną kopią oryginału. Emiter normalizuje białe znaki i komentarze, lecz zachowuje sekwencję operatorów oraz wartości operandów dokładnie. Enum intencji ma dokładnie dwa przypadki — sanityzację (redakcję) oraz osadzanie steganograficzne — i celowo nie ma przypadku ogólnego, dzięki czemu analiza statyczna może wykryć niezamierzone użycie.

Dlaczego działa w ten sposób

Projection odmawia bycia edytorem PDF ogólnego przeznaczenia. Emisja odbudowuje świeży strumień zawartości z płaskiej listy tokenów, więc oryginał nigdy nie jest modyfikowany w miejscu. To właśnie ten jednokierunkowy model sprawia, że redakcja jest godna zaufania: usunięte tokeny są nieobecne w wyniku, a nie zamalowane. Dlatego emit() wymaga jawnej ProjectionIntent, a enum oferuje wyłącznie sanityzację oraz osadzanie steganograficzne — bez przypadku ogólnego. Analiza statyczna może wtedy oznaczyć każdą emisję pozbawioną zadeklarowanego, znanego celu. Projekt wymienia wygodę edycji na gwarancję, że destrukcyjna intencja jest zawsze widoczna w miejscu wywołania.

Tło projektowe: Redaction is not a black rectangle.

Kontrakt zachowania

tokenize($contentStream) zwraca listę tokenów obejmujących ciągi znaków, nazwy, liczby, tablice, słowniki, wartości logiczne, null oraz operatory.
emit($tokens, $intent) wymaga jawnej intencji; system typów wymusza to w miejscu wywołania.
Wynik roundTrip() nie jest identyczny bajtowo z wejściem, lecz sekwencja operatorów i wartości operandów są zgodne.
Emiter formatuje liczby tak, aby zachować rozróżnienie między liczbą całkowitą a zmiennoprzecinkową, i ponownie escapuje literały ciągów znaków.
Dwie zadeklarowane intencje to sanityzacja (destrukcyjna, nieodwracalna operacja redakcji) oraz osadzanie steganograficzne.

Przykład kodu — Szybki start

Poniższy fragment odzwierciedla udokumentowane publiczne API. Repozytorium nie dostarcza uruchamialnego przykładu dla tego modułu.

use NextPDF\Pro\Projection\ContentProjectionWriter;

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

Przykład kodu — Produkcja

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

Przypadki brzegowe i pułapki

Uruchom roundTrip() i potwierdź jego poprawność, zanim zaufasz sekwencji modyfikacji i emisji. Traktuj nieudany round-trip jako warunek zatrzymania.
Intencja sanityzacji jest nieodwracalna. Usuniętej zawartości nie można odzyskać z wyniku.
Emiter normalizuje białe znaki i usuwa komentarze, więc porównanie bajtowe z oryginałem będzie się różnić nawet dla niezmodyfikowanego round-tripu.

Wydajność

Tokenizacja i emisja są liniowe względem długości strumienia zawartości. Tokenizer ogranicza odczyty escape’ów oktalnych i obsługę ciągów szesnastkowych. Nie ma opublikowanej wartości przepustowości. Mierz na reprezentatywnych strumieniach zawartości.

Uwagi dotyczące bezpieczeństwa

Wymagany argument intencji zapobiega nadużyciu jako edytor ogólnego przeznaczenia. Intencja sanityzacji jest destrukcyjna i nieodwracalna; najpierw zweryfikuj round-trip i potwierdź zredagowany wynik przed dystrybucją. Ten moduł nie loguje żadnej zawartości.

Konformancja

Tokenizacja jest zgodna z konwencjami leksykalnymi i konwencjami strumienia zawartości w ISO 32000-2; źródło opisuje odpowiednie klauzule. Korpus RAG był niedostępny w czasie tworzenia, więc ta strona nie podaje żadnych zewnętrznych identyfikatorów klauzul i ogranicza twierdzenia o konformancji do zachowania zweryfikowanego testami modułu.

Uwaga o granicy Enterprise

Enterprise nie zmienia zachowania Projection. Enterprise dodaje wyższej warstwy funkcje prywatności i zgodności udokumentowane osobno; nie są one wymagane do korzystania z API projekcji.

Rozwiązanie awaryjne / alternatywa Core

Nie ma odpowiednika Core. Bez Pro wywołujący muszą zbudować własny tokenizer strumienia zawartości; model projekcji bramkowanej intencją to dodatek dostępny wyłącznie w Pro.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.