AST

W skrócie

Moduł AST przekształca PDF w niezmienne, nawigowalne drzewo dokumentu. Korzysta z otagowanego drzewa struktury, gdy jest ono obecne, i przechodzi na heurystyczny budowniczy dla nieotagowanych dokumentów, dołączając do każdego węzła prostokąty obejmujące oraz tekst.

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 wczytuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Nie istnieje flaga licencji dla poszczególnych funkcji. Kod jest dostarczany z edycją Pro; zachowaniem budowy rządzi w całości AstBuildOptions (limity zasobów i zakresy stron), a nie przełącznik licencji.

Instalacja

composer require nextpdf/pro:^3

Kod znajduje się pod przestrzenią nazw NextPDF\Pro\Ast.

Przegląd koncepcyjny

AstBuilder orkiestruje potok od PDF do drzewa: sprawdź pamięć podręczną, odrzuć wcześnie zaszyfrowane wejście, odczytaj drzewo struktury dla otagowanych plików PDF, w przeciwnym razie przejdź na ścieżkę nieotagowaną, dołącz prostokąty obejmujące z analizy strumienia treści, a następnie zbuforuj wynik. Wynikiem jest AstDocument, którego węzły są niezmienne; aktualizacje rekonstruują dotknięte poddrzewo od dołu do góry, zamiast modyfikować je w miejscu.

Dla nieotagowanych plików PDF istnieją dwie strategie zastępcze: nagie rozwiązanie zastępcze oraz opcjonalny heurystyczny budowniczy (AstBuildOptions::$useHeuristic). Moduł dostarcza również ścieżkę emitera, która potrafi zapisać AST z powrotem do PDF i zweryfikować wynik, a także dziennik mutacji do śledzenia zmian zastosowanych do drzewa.

Dlaczego działa to w ten sposób

Drzewo jest niezmienne z założenia. Każda edycja odbudowuje wyłącznie dotkniętą ścieżkę od korzenia do węzła i współdzieli nietknięte poddrzewa poprzez tożsamość, więc zbudowany AstDocument można bezpiecznie przechowywać, buforować i przekazywać współbieżnym czytelnikom bez kopii obronnych. Odzwierciedla to sposób, w jaki sam PDF zmienia się na dysku: ścieżka zapisu zwrotnego dopisuje przyrostową aktualizację przez AstWriter, zamiast przepisywać plik, pozostawiając oryginalne bajty — oraz wszelkie istniejące podpisy — nienaruszone. Rewizję typu tylko-do-dopisywania łatwo również zweryfikować strukturalnie, dlatego AstWriter może sprawdzić własny wynik przed jego zwróceniem. Rekonstruowanie poddrzew zamiast modyfikowania ich w miejscu to jedna decyzja, która czyni moduł zarazem nawigowalnym i bezpiecznym do edycji.

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

Kontrakt zachowania

• AstBuilder::build($sourceHash) przyjmuje pełny SHA-256 w zapisie szesnastkowym źródłowego PDF i zwraca AstDocument.
• Zaszyfrowane pliki PDF są odrzucane z dedykowanym błędem nieobsługiwanego szyfrowania; odszyfruj przed budowaniem.
• Gdy nie ma drzewa struktury, budowniczy automatycznie korzysta ze ścieżki nieotagowanej — heurystycznej, jeśli jest włączona, w przeciwnym razie nagiego rozwiązania zastępczego.
• Limity zasobów w AstBuildOptions (maksymalna liczba węzłów, maksymalna głębokość, maksymalna pamięć, limit czasu rzeczywistego) powodują błąd limitu budowy lub przekroczenia czasu budowy, zamiast nieograniczonej pracy.
• Klucz pamięci podręcznej obejmuje skrót źródła oraz skrót opcji, więc dwie budowy z identycznymi wejściami i opcjami zwracają to samo drzewo.
• AstNode jest niezmienny; konsumenci otrzymują nowe instancje węzłów, gdy drzewo się zmienia.

Przykład kodu — Szybki start

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

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$builder = new AstBuilder($pdfReader, new AstBuildOptions());
$document = $builder->build($sha256OfPdf);

Przykład kodu — Produkcja

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$options = new AstBuildOptions(
    maxNodes: 100_000,
    maxDepth: 200,
    maxMemoryBytes: 256 * 1024 * 1024,
    timeoutSeconds: 30.0,
    useHeuristic: true,
);

$builder = new AstBuilder($pdfReader, $options, $astCache);

try {
    $document = $builder->build($sha256OfPdf);
} catch (\NextPDF\Pro\Ast\Exception\AstUnsupportedEncryptionException $e) {
    // Decrypt the source first, then retry.
}

Przypadki brzegowe i pułapki

• Strony, których strumienia treści nie da się sparsować, są pomijane podczas dołączania prostokątów obejmujących; drzewo jest nadal zwracane, tyle że bez prostokątów dla tych stron.
• Heurystyczny budowniczy jest włączany opcjonalnie. Gdy jest wyłączony, nieotagowane pliki PDF dają zgrubniejsze drzewo z nagiego rozwiązania zastępczego.
• Zakres stron w AstBuildOptions korzysta z indeksów liczonych od 0, włącznie z końcami; pozostawienie obu granic jako null przetwarza wszystkie strony.

Wydajność

Koszt budowy skaluje się wraz z liczbą węzłów i liczbą stron; AstBuildOptions ogranicza oba. Pamięć podręczna skraca obieg dla powtarzanych budów tego samego wejścia z tymi samymi opcjami. NextPDF nie publikuje tutaj stałego czasu na dokument; limit czasu rzeczywistego (domyślnie 30 s) oraz pułap węzłów (domyślnie 100 000) ograniczają pracę w najgorszym przypadku. Zmierz na reprezentatywnych dokumentach.

Uwagi dotyczące bezpieczeństwa

Traktuj wejście jako niezaufane. Budowniczy odrzuca zaszyfrowane pliki PDF, zamiast je częściowo przetwarzać. Pułapy zasobów (węzły, głębokość, pamięć, czas) chronią przed patologicznymi lub wrogimi dokumentami. Ten moduł nie loguje żadnej treści dokumentu.

Zgodność

Ścieżka drzewa struktury odczytuje struktury otagowanego PDF zdefiniowane przez ISO 32000-2; źródło modułu adnotuje odpowiednie klauzule strumienia treści i struktury. Ponieważ korpus RAG był niedostępny w czasie tworzenia, ta strona nie deklaruje żadnych zewnętrznych identyfikatorów klauzul i ogranicza stwierdzenia o zgodności do zachowania zweryfikowanego testami modułu.

Uwaga o granicy Enterprise

Enterprise nie zmienia zachowania AST. Enterprise dodaje wyższego poziomu możliwości zgodności i archiwizacji udokumentowane osobno; nie są one wymagane do zbudowania ani skonsumowania AST.

Rozwiązanie zastępcze Core / alternatywa

Bez Pro nie ma równoważnego drzewa dokumentu; wywołujący parsują strumienie treści bezpośrednio przy użyciu prymitywów NextPDF Core. Zobacz /modules/ast/.

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.

Zobacz też

• AST — Dogłębny opis
• Projection
• Diff
• Output Pipeline