AST — pełna dokumentacja referencyjna

W skrócie

Ta strona to pełna dokumentacja referencyjna modułu Pro AST. Obejmuje publiczne powierzchnie budowy, cache, mutacji, zapisu i emisji, ich kontrakty zachowania oraz tryby awarii. Moduł parsuje załadowany PDF do niezmiennego drzewa AstDocument, stosuje rejestrowane mutacje w pamięci i zapisuje przyrostowe aktualizacje oparte na nakładkach. AstDocument i AstNode to typy wartości Core w przestrzeni nazw NextPDF\Ast; ten moduł je produkuje i konsumuje.

Dostępność i licencjonowanie

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

Nie istnieje flaga licencyjna dla poszczególnych funkcji. To funkcja edycji Pro. Zachowanie budowy jest w całości regulowane przez AstBuildOptions.

Powierzchnia publicznego API

Symbol	Parametry	Domyślne zachowanie	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
AstBuilder::__construct	PdfReader $reader, AstBuildOptions $options, ?AstCache $cache = null	Wiąże załadowany reader z opcjami budowy; cache jest opcjonalny	AstBuilder	—	Null cache oznacza, że każde wywołanie build() przebudowuje od nowa.
AstBuilder::build	string $sourceHash (pełny SHA-256 w hex bajtów PDF)	Odpytanie cache, odrzucenie szyfrowania, ścieżka drzewa struktury, rozwiązanie awaryjne dla nietagowanego, dołączenie prostokątów ograniczających, zapis do cache	AstDocument	AstUnsupportedEncryptionException, AstBuildLimitException, AstBuildTimeoutException	Trafienie w cache zwraca bez ponownego parsowania.
AstBuildOptions::__construct	?int $pageRangeStart = null, ?int $pageRangeEnd = null, int $maxNodes = 100_000, int $maxDepth = 200, ?int $estimatedTokenBudget = null, int $maxMemoryBytes = 268435456, float $timeoutSeconds = 30.0, bool $useHeuristic = false	Niezmienny obiekt wartości konfiguracji	AstBuildOptions	—	estimatedTokenBudget to wskazówka informacyjna; nie jest egzekwowany.
AstBuildOptions::pageRangeContains	int $pageIndex	Prawda, gdy indeks 0-bazowy mieści się w skonfigurowanym zakresie	bool	—	Granice null są otwarte; obie null oznaczają wszystkie strony.
AstBuildOptions::hash	—	Stabilny SHA-256 po wszystkich wartościach opcji	string	—	Równe wartości dają równe skróty między instancjami; używany jako segment klucza cache.
AstCache::__construct	CacheInterface $backend	Opakowuje dowolny backend PSR-16	AstCache	—	—
AstCache::buildKey	string $sourceHash, AstBuildOptions $options	Klucz = nextpdf_ast_v1_ + pierwsze 32 hex skrótu źródła + _ + pierwsze 16 hex skrótu opcji	string	—	Zmiany opcji automatycznie unieważniają zapisane w cache wyniki.
AstCache::get	string $cacheKey	Dekoduje ładunek JSON przez ścisłą walidację pól	?AstDocument	Nigdy nie zgłasza wyjątku; niepowodzenia zwracają null	Zniekształcone lub zmanipulowane ładunki zawodzą bezpiecznie jako brak trafienia w cache.
AstCache::set	string $cacheKey, AstDocument $document	Zapisuje JSON z 24-godzinnym TTL, następnie weryfikuje przez natychmiastowy odczyt zwrotny	void	AstWriteVerificationException (przestrzeń nazw Exception)	Niepowodzenie zapisu backendu lub nieudany round-trip zgłasza wyjątek.
AstCache::delete	string $cacheKey	Usunięcie best-effort	void	Nigdy nie zgłasza wyjątku	Niepowodzenia usunięcia backendu są pochłaniane.
AstCache::has	string $cacheKey	Sprawdzenie istnienia best-effort	bool	Nigdy nie zgłasza wyjątku; niepowodzenia zwracają false	—
AstMutator::updateNode	AstDocument $document, string $nodeId, array $updates	Zastępuje text_content, zapisuje wpis Updated	AstDocument (nowa instancja)	InvalidArgumentException	Stosowany jest tylko klucz text_content; nieznane klucze są ignorowane.
AstMutator::deleteNode	AstDocument $document, string $nodeId	Usuwa węzeł z drzewa w pamięci, zapisuje wpis Deleted	AstDocument (nowa instancja)	InvalidArgumentException	Tylko usunięcie w pamięci; zobacz zastrzeżenie o redakcji poniżej.
AstMutator::getMutationLog	—	Zwraca współdzieloną instancję dziennika	MutationLog	—	Przekaż ten sam dziennik do AstWriter.
AstMutator::resetLog	—	Odrzuca wszystkie zapisane mutacje	void	—	Rozpoczyna nowy dziennik.
MutationLog	record, all, isEmpty, count, forNode, mutatedNodeIds	Dziennik w pamięci tylko do dopisywania, zachowana kolejność wstawiania	zależnie od metody	—	forNode zwraca najnowszy wpis dla węzła; wygrywa ostatni wpis.
MutationEntry::__construct	string $nodeId, MutationType $type, ?AstNode $originalNode, ?AstNode $mutatedNode, DateTimeImmutable $timestamp	Niezmienny rekord jednej mutacji	MutationEntry	—	originalNode jest null dla Inserted; mutatedNode jest null dla Deleted.
MutationType	przypadki enum Updated, Inserted, Deleted	Klasyfikacja oparta na stringu	—	—	Deleted w trybie OVERLAY ukrywa zawartość; nie usuwa bajtów.
AstWriter::write	string $originalPdfBytes, MutationLog $log	Dopisuje aktualizację przyrostową, której strumienie nakładki pokrywają zmutowane prostokąty ograniczające	string (zmodyfikowane bajty PDF)	AstWriteException	Pusty dziennik zwraca wejście bez zmian. Wpisy Inserted oraz wpisy bez prostokąta ograniczającego są pomijane.
AstWriter::writeAndVerify	string $originalPdfBytes, MutationLog $log	Uruchamia write(), następnie strukturalną kontrolę wyjścia	string (zweryfikowane bajty PDF)	AstWriteException, AstWriteVerificationException (przestrzeń nazw Writer)	Weryfikacja jest strukturalna, nie semantyczna.
AstPdfEmitter::emit	AstNode $root, BinaryBuffer $buffer, ObjectRegistry $registry, array $pageObjects	Zapisuje StructTreeRoot, łańcuch StructElem oraz ParentTree dla dostarczonego drzewa	EmitResult	AstEmitException	Korzeń musi być węzłem Document z dziećmi. Emiter round-trip do weryfikacji drzewa struktury.
EmitResult::__construct	int $structTreeRootObject, int $rootElementObject, int $parentTreeObject, int $elementObjectCount, int $parentTreeNextKey	Niezmienny rekord wyemitowanych identyfikatorów obiektów	EmitResult	—	—

public function build(string $sourceHash): AstDocument

public function updateNode(AstDocument $document, string $nodeId, array $updates): AstDocument
public function deleteNode(AstDocument $document, string $nodeId): AstDocument

public function write(string $originalPdfBytes, MutationLog $log): string
public function writeAndVerify(string $originalPdfBytes, MutationLog $log): string

Hierarchia wyjątków

• NextPDF\Pro\Ast\Exception\AstException rozszerza RuntimeException — podstawa hierarchii budowy.
• AstBuildLimitException rozszerza AstException — przekroczono pułap węzłów, głębokości lub pamięci.
• AstBuildTimeoutException rozszerza AstBuildLimitException — upłynął limit czasu zegarowego budowy.
• AstNoStructTreeException rozszerza AstException — brak drzewa struktury. AstBuilder::build() przechwytuje go wewnętrznie i przechodzi na rozwiązanie awaryjne; wywołujący build() go nie obserwują.
• AstUnsupportedEncryptionException rozszerza AstException — wejściowy PDF jest zaszyfrowany.
• NextPDF\Pro\Ast\Exception\AstWriteVerificationException rozszerza AstException — weryfikacja zapisu cache nie powiodła się.
• NextPDF\Pro\Ast\Writer\AstWriteException rozszerza RuntimeException — niepowodzenie wejścia lub struktury writera.
• NextPDF\Pro\Ast\Writer\AstWriteVerificationException rozszerza AstWriteException — strukturalna weryfikacja po zapisie nie powiodła się.

Istnieją dwie odrębne klasy AstWriteVerificationException w różnych przestrzeniach nazw. AstCache::set() zgłasza klasę z przestrzeni nazw Exception; AstWriter::writeAndVerify() zgłasza klasę z przestrzeni nazw Writer. Dopasuj przestrzeń nazw w klauzulach catch.

Kontrakt zachowania

AstBuilder::build($sourceHash) wymaga pełnego SHA-256 w hex bajtów źródłowych. Potok to: opcjonalne odpytanie cache, odrzucenie szyfrowania, ścieżka drzewa struktury, rozwiązanie awaryjne dla nietagowanego, dołączenie prostokątów ograniczających, opcjonalny zapis do cache.

Klucz cache łączy skrót źródła ze skrótem AstBuildOptions. Skrót opcji jest stabilny między instancjami o identycznych wartościach, więc identyczne wejścia i opcje zwracają to samo drzewo. Gdy nie dostarczono cache, każde wywołanie buduje od nowa. Ładunki w cache to JSON, nigdy natywna serializacja PHP: ścieżka odczytu waliduje każde pole i tworzy instancje wyłącznie typów wartości AST, więc zatruty wpis cache nie może wywołać wstrzyknięcia obiektu i degraduje się do braku trafienia w cache.

Ścieżka drzewa struktury uruchamia się, gdy drzewo struktury jest obecne. Pułapy zasobów — liczba węzłów, głębokość, delta pamięci i czas zegarowy — są egzekwowane podczas odczytu drzewa struktury i zgłaszają AstBuildLimitException lub AstBuildTimeoutException. Jeśli czytnik zgłosi brak drzewa struktury, builder przełącza się na ścieżkę nietagowaną: builder heurystyczny, gdy useHeuristic jest prawdą, w przeciwnym razie goły builder awaryjny. Prostokąty ograniczające są dołączane przez analizę strumienia zawartości każdej strony z zakresu; strona, której strumienia zawartości nie da się sparsować, jest pomijana i pozostawia resztę drzewa nienaruszoną.

AstNode jest niezmienny. Aktualizacje drzewa przebudowują dotknięte węzły od dołu do góry; niezmienione poddrzewa są zwracane przez tożsamość. AstMutator przestrzega tego samego kontraktu: każda mutacja zwraca nowy AstDocument, przebudowuje tylko ścieżkę od korzenia do celu i zapisuje MutationEntry we współdzielonym MutationLog.

AstWriter stosuje MutationLog w trybie OVERLAY jako aktualizację przyrostową tylko do dopisywania: nowe strumienie zawartości nakładki, zaktualizowane obiekty stron, sekcję odsyłaczy obejmującą tylko nowe obiekty oraz trailer, którego /Prev wskazuje na poprzedni startxref. Oryginalne bajty pozostają nienaruszone, zgodnie z modelem aktualizacji przyrostowej z ISO 32000-2:2020, 7.5.6. Tekst zastępczy rysowany dla wpisów Updated escapuje \, ( oraz ) w łańcuchach literalnych, zgodnie z ISO 32000-2:2020, 7.3.4.2.

AstPdfEmitter::emit() jest symetryczną odwrotnością odczytu drzewa struktury: drzewa wyprodukowane przez czytnik przechodzą round-trip do strukturalnie równoważnych drzew, z dokładnością do renumeracji node-id i udokumentowanych klas kanonikalizacji. MCID obecne na węzłach są re-emitowane dosłownie, nigdy nie są realokowane.

Przypadki brzegowe i tryby awarii

• Zaszyfrowane wejście jest odrzucane przed jakąkolwiek pracą nad drzewem; nie ma częściowego wyniku drzewa dla zaszyfrowanych plików PDF. Najpierw odszyfruj.
• Pułapy zasobów: maks. liczba węzłów (domyślnie 100,000), maks. głębokość (domyślnie 200), maks. pamięć (domyślnie 256 MiB), limit czasu zegarowego (domyślnie 30 s). Przekroczenie pułapu zgłasza AstBuildLimitException; przekroczenie czasu zgłasza AstBuildTimeoutException, podklasę.
• Zakres stron jest 0-bazowy i obejmuje końce; granice null oznaczają wszystkie strony.
• Strona, której strumienia zawartości nie da się sparsować, jest pomijana podczas dołączania prostokątów ograniczających; reszta drzewa pozostaje nienaruszona.
• AstCache::get() nigdy nie zgłasza wyjątku: zniekształcone, zmanipulowane lub niebędące stringiem ładunki zwracają null i wymuszają przebudowę. AstCache::set() zawodzi głośno, gdy zapis backendu lub natychmiastowy odczyt zwrotny się nie powiedzie.
• AstMutator zgłasza InvalidArgumentException, gdy nie znaleziono identyfikatora węzła. Nieznane klucze aktualizacji są po cichu ignorowane; stosowany jest tylko text_content.
• AstWriter::write() zgłasza AstWriteException, gdy wejściu brakuje nagłówka %PDF- lub możliwego do zlokalizowania startxref. Wpisy bez prostokąta ograniczającego są po cichu pomijane. Strony, których nie da się zlokalizować skanowaniem obiektów — na przykład pod skompresowanymi strumieniami odsyłaczy — są pomijane; jeśli nie można zastosować żadnej nakładki, bajty wejściowe są zwracane bez zmian.
• Wyjście OVERLAY nie jest redakcją. Biały prostokąt i ponownie narysowany tekst są dopisywane; oryginalne bajty zawartości pozostają w pliku i można je odzyskać surową ekstrakcją. Nie używaj tego do usuwania danych zgodnie z art. 17 RODO ani do prawnej redakcji. W drzewie źródłowym istnieje writer w trybie rekonstrukcji, ale jest oznaczony jako wewnętrzny, nie jest gotowy do produkcji i znajduje się poza wspieraną powierzchnią API.
• Geometria nakładki zakłada A4 w orientacji pionowej (595 x 842 pt), ponieważ writer nie odczytuje MediaBox strony. Na stronach innych niż A4 nakładka może być lekko niedopasowana; wyjście pozostaje strukturalnie poprawne.
• writeAndVerify() sprawdza tylko strukturę: nagłówek, końcowy %%EOF oraz wzrost wyjścia. Nie parsuje semantycznie zmutowanego dokumentu ponownie.
• AstPdfEmitter::emit() zgłasza AstEmitException, gdy korzeń nie jest węzłem Document lub nie ma dzieci. Towarzyszące wpisy OBJR (adnotacji) nie są emitowane w tym wydaniu.
• Ten moduł nie wykonuje żadnych operacji kryptograficznych i nie definiuje żadnego zachowania specyficznego dla FIPS. SHA-256 pojawia się wyłącznie jako adresowanie treści dla kluczy cache.

Konformancja

Ścieżka drzewa struktury odczytuje mechanizmy struktury logicznej tagowanego PDF zdefiniowane przez ISO 32000-2; korpus RAG dostępny w czasie tworzenia nie obejmuje klauzul struktury logicznej, więc to stwierdzenie jest oparte na produkcie z adnotacji źródłowych. Układ aktualizacji przyrostowej writera jest zgodny z ISO 32000-2:2020, 7.5.6 (cytowane poniżej), a jego escapowanie łańcuchów literalnych jest zgodne z ISO 32000-2:2020, 7.3.4.2 (cytowane poniżej).

Te stwierdzenia opisują możliwości względem cytowanych klauzul. NextPDF nie posiada żadnej certyfikacji zgodności, a wsparcie dla klauzuli nie jest deklaracją certyfikacji.

Uwagi programistyczne

• Twórz jeden AstBuilder na załadowany PdfReader. Ponownie używaj AstCache między budowami, aby zamortyzować parsowanie; konstrukcja klucza sprawia, że zmiany opcji same się unieważniają.
• Współdziel jeden MutationLog między AstMutator a AstWriter, aby writer zastosował dokładnie zarejestrowaną sesję. Wywołuj resetLog() między niezależnymi sesjami edycji.
• Ustaw useHeuristic na true dla dokumentów nietagowanych, gdy grupowanie wywodzone z układu jest preferowane względem gołego drzewa awaryjnego.
• Budowy są deterministyczne dla identycznych bajtów i opcji; polegaj na tym w testach typu snapshot.
• Przechwytuj niepowodzenia budowy przez hierarchię NextPDF\Pro\Ast\Exception, a niepowodzenia zapisu przez hierarchię NextPDF\Pro\Ast\Writer; obie nie współdzielą bazy poniżej RuntimeException.

Granica publikacji

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

Zobacz także

• AST — przegląd funkcji
• Projection — pełna dokumentacja referencyjna
• Output Pipeline — pełna dokumentacja referencyjna