Pro edycja

Writer

W skrócie

Moduł Writer dopisuje rewizje aktualizacji przyrostowej do PDF i pakuje małe obiekty do Object Streams. Pisarz przyrostowy egzekwuje regułę tylko-dopisywanie: bajty, które istniały przed rewizją, nie mogą się zmienić.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję. Nie ma osobnej flagi licencji na poziomie pojedynczej funkcji; kod jest dostarczany wraz z edycją Pro.

Instalacja

composer require nextpdf/pro:^3

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

Przegląd koncepcyjny

Dostarczane są dwie możliwości:

IncrementalUpdateWriter zapisuje nową rewizję. Ponownie zapisuje katalog ze scalonymi wpisami, dopisuje tradycyjną tablicę odsyłaczy (cross-reference) dla nowych i zmodyfikowanych obiektów oraz zapisuje przyczepkę (trailer) wiążącą z poprzednią rewizją. Egzekwuje regułę tylko-dopisywanie w trybie fail-closed.
ObjectStreamWriter grupuje małe obiekty w jeden skompresowany Object Stream. Zmniejsza to rozmiar tablicy odsyłaczy i poprawia kompresję. Odrzuca obiekty, które przekroczyłyby maksymalny rozmiar strumienia, oraz odrzuca pusty strumień.

Reguła tylko-dopisywanie chroni istniejące podpisy. Każdy bajt, który bufor przechowywał przed rewizją, musi pojawić się niezmieniony na tej samej pozycji po rewizji. Jeśli jakikolwiek wcześniejszy bajt się zmieni, pisarz zgłasza błąd i nie wytwarza wyniku.

Dlaczego działa to w ten sposób

Kluczowym wyborem jest to, gdzie umieszczono bramę tylko-dopisywanie. Znajduje się ona na poziomie pisarza, a nie tylko w wyżej położonych orkiestratorach, dzięki czemu każdy obecny i przyszły wywołujący dziedziczy pokrycie w trybie fail-closed. Sprawdzenie jest czystym testem równości prefiksu: pisarz robi migawkę prefiksu bufora przed dopisaniem, a następnie potwierdza, że każdy wcześniejszy bajt pozostał niezmieniony. Chroni to każdy podpis, którego /ByteRange obejmował prefiks, ponieważ jeden zmieniony bajt po cichu by go unieważnił. Tradycyjne tablice odsyłaczy oraz wskaźnik /Prev niosą nową rewizję, ponieważ aktualizacje przyrostowe muszą dopisywać, a nie przepisywać. Koszt weryfikacji jest liniowy względem istniejącego prefiksu i ten koszt jest akceptowany rozmyślnie: integralność podpisanych bajtów przeważa nad dodatkową kopią.

Tło projektowe: Aktualizacje przyrostowe i dlaczego mają znaczenie.

Kontrakt zachowania

IncrementalUpdateWriter::writeRevision(...) zwraca przesunięcie bajtowe nowej tablicy odsyłaczy, dzięki czemu możesz łańcuchować kolejne rewizje.
Pisarz weryfikuje, że oryginalny prefiks jest równy bajtowo przed zapisem i po nim. Rozbieżność zgłasza wyjątek pisarza niosący stan naruszenia reguły tylko-dopisywanie.
Nowa rewizja używa tradycyjnej tablicy odsyłaczy oraz przyczepki ze wskaźnikiem /Prev; mieszanie tablic i strumieni między rewizjami jest dozwolone.
ObjectStreamWriter::addObject() zgłasza błąd przepełnienia, gdy dodanie obiektu przekroczyłoby maksymalny rozmiar strumienia (65 536 bajtów bez kompresji dla indeksu wraz z treścią).
ObjectStreamWriter::build() zgłasza błąd, gdy nie dodano żadnych obiektów; w przeciwnym razie zwraca skompresowaną zawartość Object Stream.

Przykład kodu — Szybki start

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

use NextPDF\Pro\Writer\ObjectStreamWriter;

$writer = new ObjectStreamWriter();
$writer->addObject(10, $serializedObjectBody);
$objStm = $writer->build();

Przykład kodu — Produkcja

use NextPDF\Pro\Writer\IncrementalUpdateWriter;

$newXrefOffset = IncrementalUpdateWriter::writeRevision(
    $buffer,
    $registry,
    $prevXrefOffset,
    $catalogObject,
    $catalogEntries,
    $catalogUpdates,
    $newObjectNumbers,
    $fileId,
);
// A WriterException here means the append-only rule was violated.
// Treat it as a hard failure; do not emit the output.

Przypadki brzegowe i pułapki

Sprawdzenie reguły tylko-dopisywanie kopiuje istniejący prefiks. Koszt rośnie wraz z rozmiarem już zapisanego dokumentu. Ten koszt jest zamierzony i chroni podpisane bajty.
Limit rozmiaru Object Stream dotyczy połączonego indeksu i treści przed kompresją. Odpowiednio grupuj obiekty.
Object Streams nie mogą zawierać pewnych typów obiektów (na przykład słownika szyfrowania). Umieść je jako bezpośrednie obiekty pośrednie.

Wydajność

Weryfikacja tylko-dopisywanie jest liniowa względem rozmiaru istniejącego prefiksu dokumentu. Pakowanie Object Stream zmniejsza rozmiar odsyłaczy i poprawia kompresję kosztem jednego dodatkowego przebiegu kompresji. Nie ma opublikowanej wartości przepustowości. Zmierz na reprezentatywnych dokumentach.

Uwagi dotyczące bezpieczeństwa

Pisarz przyrostowy jest fail-closed. Jeśli ścieżka kodu miałaby zmienić bajt objęty wcześniejszym podpisem, pisarz zgłasza błąd zamiast wytwarzać dokument. Chroni to integralność podpisu w przepływach z łańcuchowaniem rewizji. Żadna treść dokumentu nie jest logowana.

Zgodność ze standardami

Źródło opatruje adnotacjami gramatykę aktualizacji przyrostowej i model Object Stream w ISO 32000-2 oraz wymagania łańcuchowania rewizji w profilu PAdES ETSI EN 319 142-1. Ponieważ korpus RAG był niedostępny w chwili tworzenia, ta strona powtarza wyłącznie odniesienia do klauzul, które deklaruje samo źródło, i nie formułuje żadnych dodatkowych zewnętrznych identyfikatorów klauzul.

Uwaga o granicy Enterprise

Enterprise dodaje funkcje cyklu życia podpisu wyższego poziomu (walidacja długoterminowa i odnawianie), które bazują na aktualizacjach przyrostowych na poziomie zachowania. Moduł Writer dostarcza wyłącznie prymityw rewizji; te funkcje wyższego poziomu są dokumentowane osobno i nie są wymagane do zapisania rewizji.

Rozwiązanie awaryjne / alternatywa w Core

Bez Pro użyj bazowego pisarza NextPDF Core; rewizje aktualizacji przyrostowej z bramą tylko-dopisywanie oraz pakowanie Object Stream są dodatkami Pro. Zobacz /modules/writer/.

Granica publikacji

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