AST — Derinlemesine başvuru

Bir bakışta

Bu sayfa, Pro AST modülünün derinlemesine başvurusudur. Genel build, cache, mutation, write ve emit yüzeylerini, bunların davranış sözleşmelerini ve arıza modlarını kapsar. Modül, yüklenmiş bir PDF’i değişmez bir AstDocument ağacına ayrıştırır, günlüğe kaydedilen bellek içi değişiklikleri uygular ve overlay tabanlı artımlı güncellemeler yazar. AstDocument ve AstNode, NextPDF\Ast ad alanındaki Core değer türleridir; bu modül onları üretir ve tüketir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Özellik başına lisans bayrağı yoktur. Bu, bir Pro sürümü yeteneğidir. Derleme davranışı tamamen AstBuildOptions tarafından yönetilir.

Genel API yüzeyi

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
AstBuilder::__construct	PdfReader $reader, AstBuildOptions $options, ?AstCache $cache = null	Yüklenmiş bir okuyucuyu derleme seçeneklerine bağlar; önbellekleme isteğe bağlıdır	AstBuilder	—	Null önbellek, her build() çağrısının yeniden oluşturduğu anlamına gelir.
AstBuilder::build	string $sourceHash (PDF baytlarının tam SHA-256 onaltılık değeri)	Önbellek araması, şifreleme reddi, yapı ağacı yolu, etiketsiz geri dönüş, sınırlayıcı kutu eklenmesi, önbellek depolaması	AstDocument	AstUnsupportedEncryptionException, AstBuildLimitException, AstBuildTimeoutException	Bir önbellek isabeti, yeniden ayrıştırma olmadan döndürür.
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	Değişmez yapılandırma değer nesnesi	AstBuildOptions	—	estimatedTokenBudget bilgilendirici bir ipucudur; zorunlu tutulmaz.
AstBuildOptions::pageRangeContains	int $pageIndex	0 tabanlı dizin, yapılandırılan aralığın içine düştüğünde doğru	bool	—	Null sınırlar açık uçludur; her ikisi de null ise tüm sayfalar anlamına gelir.
AstBuildOptions::hash	—	Tüm seçenek değerleri üzerinde kararlı SHA-256	string	—	Eşit değerler, örnekler arasında eşit karmalar üretir; önbellek anahtarı bölümü olarak kullanılır.
AstCache::__construct	CacheInterface $backend	Herhangi bir PSR-16 arka ucunu sarar	AstCache	—	—
AstCache::buildKey	string $sourceHash, AstBuildOptions $options	Anahtar = nextpdf_ast_v1_ + kaynak karmasının ilk 32 onaltılığı + _ + seçenekler karmasının ilk 16 onaltılığı	string	—	Seçenek değişiklikleri, önbelleğe alınmış sonuçları otomatik olarak geçersiz kılar.
AstCache::get	string $cacheKey	Bir JSON yükünü katı alan başına doğrulamayla çözer	?AstDocument	Asla fırlatmaz; başarısızlıklar null döndürür	Hatalı biçimlendirilmiş veya kurcalanmış yükler, önbellek ıskası olarak kapalı biçimde başarısız olur.
AstCache::set	string $cacheKey, AstDocument $document	JSON’u 24 saatlik bir TTL ile depolar, ardından anında geri okumayla doğrular	void	AstWriteVerificationException (Exception ad alanı)	Arka uç yazma başarısızlığı veya başarısız bir gidiş-dönüş, hata fırlatır.
AstCache::delete	string $cacheKey	En iyi çaba temelli kaldırma	void	Asla fırlatmaz	Arka uç silme başarısızlıkları yutulur.
AstCache::has	string $cacheKey	En iyi çaba temelli varlık denetimi	bool	Asla fırlatmaz; başarısızlıklar false döndürür	—
AstMutator::updateNode	AstDocument $document, string $nodeId, array $updates	text_content değerini değiştirir, bir Updated girişi kaydeder	AstDocument (yeni örnek)	InvalidArgumentException	Yalnızca text_content anahtarı uygulanır; bilinmeyen anahtarlar yok sayılır.
AstMutator::deleteNode	AstDocument $document, string $nodeId	Düğümü bellek içi ağaçtan kaldırır, bir Deleted girişi kaydeder	AstDocument (yeni örnek)	InvalidArgumentException	Yalnızca bellek içi kaldırma; aşağıdaki redaksiyon uyarısına bakın.
AstMutator::getMutationLog	—	Paylaşılan günlük örneğini döndürür	MutationLog	—	Aynı günlüğü AstWriter’a geçirin.
AstMutator::resetLog	—	Kaydedilen tüm değişiklikleri atar	void	—	Yeni bir günlük başlatır.
MutationLog	record, all, isEmpty, count, forNode, mutatedNodeIds	Yalnızca ekleme yapılan bellek içi günlük, ekleme sırası korunur	yönteme göre	—	forNode, bir düğüm için en son girişi döndürür; son giriş kazanır.
MutationEntry::__construct	string $nodeId, MutationType $type, ?AstNode $originalNode, ?AstNode $mutatedNode, DateTimeImmutable $timestamp	Bir değişikliğin değişmez kaydı	MutationEntry	—	originalNode, Inserted için null’dur; mutatedNode, Deleted için null’dur.
MutationType	enum durumları Updated, Inserted, Deleted	String destekli sınıflandırma	—	—	OVERLAY altında Deleted, içeriği gizler; baytları silmez.
AstWriter::write	string $originalPdfBytes, MutationLog $log	Overlay akışları değiştirilen sınırlayıcı kutuları kapsayan bir artımlı güncelleme ekler	string (değiştirilmiş PDF baytları)	AstWriteException	Boş bir günlük, girdiyi değiştirmeden döndürür. Inserted girişleri ve sınırlayıcı kutusu olmayan girişler atlanır.
AstWriter::writeAndVerify	string $originalPdfBytes, MutationLog $log	write() çalıştırır, ardından yapısal bir çıktı denetimi yapar	string (doğrulanmış PDF baytları)	AstWriteException, AstWriteVerificationException (Writer ad alanı)	Doğrulama semantik değil, yapısaldır.
AstPdfEmitter::emit	AstNode $root, BinaryBuffer $buffer, ObjectRegistry $registry, array $pageObjects	Sağlanan ağaç için bir StructTreeRoot, StructElem zinciri ve ParentTree yazar	EmitResult	AstEmitException	Kök, alt öğeleri olan bir Document düğümü olmalıdır. Yapı ağacı doğrulaması için gidiş-dönüş yayıcısı.
EmitResult::__construct	int $structTreeRootObject, int $rootElementObject, int $parentTreeObject, int $elementObjectCount, int $parentTreeNextKey	Yayılan nesne tanımlayıcılarının değişmez kaydı	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

İstisna hiyerarşisi

• NextPDF\Pro\Ast\Exception\AstException, RuntimeException’ı genişletir — derleme hiyerarşisinin temeli.
• AstBuildLimitException, AstException’ı genişletir — bir düğüm, derinlik veya bellek tavanı aşıldı.
• AstBuildTimeoutException, AstBuildLimitException’ı genişletir — gerçek zamanlı derleme zaman aşımı doldu.
• AstNoStructTreeException, AstException’ı genişletir — hiçbir yapı ağacı yok. AstBuilder::build() bunu dahili olarak yakalar ve geri döner; build() çağıranlar bunu gözlemlemez.
• AstUnsupportedEncryptionException, AstException’ı genişletir — girdi PDF’i şifrelenmiştir.
• NextPDF\Pro\Ast\Exception\AstWriteVerificationException, AstException’ı genişletir — önbellek yazma doğrulaması başarısız oldu.
• NextPDF\Pro\Ast\Writer\AstWriteException, RuntimeException’ı genişletir — yazıcı girdi veya yapı başarısızlığı.
• NextPDF\Pro\Ast\Writer\AstWriteVerificationException, AstWriteException’ı genişletir — yazma sonrası yapısal doğrulama başarısız oldu.

Farklı ad alanlarında iki ayrı AstWriteVerificationException sınıfı bulunur. AstCache::set(), Exception ad alanı sınıfını fırlatır; AstWriter::writeAndVerify(), Writer ad alanı sınıfını fırlatır. catch cümlelerinde ad alanını eşleştirin.

Davranış sözleşmesi

AstBuilder::build($sourceHash), kaynak baytlarının tam SHA-256 onaltılık değerini gerektirir. İşlem hattı şudur: isteğe bağlı önbellek araması, şifreleme reddi, yapı ağacı yolu, etiketsiz geri dönüş, sınırlayıcı kutu eklenmesi, isteğe bağlı önbellek depolaması.

Önbellek anahtarı, kaynak karmasını AstBuildOptions karmasıyla birleştirir. Seçenekler karması, özdeş değerlere sahip örnekler arasında kararlıdır; bu nedenle özdeş girdiler ve seçenekler aynı ağacı döndürür. Hiçbir önbellek sağlanmadığında, her çağrı yeniden oluşturur. Önbelleğe alınmış yükler JSON’dur, asla yerel PHP serileştirmesi değildir: okuma yolu her alanı doğrular ve yalnızca AST değer türlerini örnekler, bu nedenle zehirlenmiş bir önbellek girişi nesne enjeksiyonu tetikleyemez ve önbellek ıskasına indirgenir.

Yapı ağacı yolu, bir yapı ağacı mevcut olduğunda çalışır. Kaynak tavanları — düğüm sayısı, derinlik, bellek deltası ve gerçek zaman — yapı ağacı okuması sırasında zorunlu tutulur ve AstBuildLimitException veya AstBuildTimeoutException fırlatır. Okuyucu hiçbir yapı ağacı raporlamazsa, oluşturucu etiketsiz yola geçer: useHeuristic doğru olduğunda sezgisel oluşturucu, aksi takdirde yalın geri dönüş oluşturucusu. Sınırlayıcı kutular, aralıktaki her sayfanın içerik akışı analiz edilerek eklenir; içerik akışı ayrıştırılamayan bir sayfa atlanır ve ağacın geri kalanını bozulmadan bırakır.

AstNode değişmezdir. Ağaç güncellemeleri, etkilenen düğümleri aşağıdan yukarıya yeniden oluşturur; değişmemiş alt ağaçlar özdeşlikle döndürülür. AstMutator aynı sözleşmeyi izler: her değişiklik yeni bir AstDocument döndürür, yalnızca kökten hedefe giden yolu yeniden oluşturur ve paylaşılan MutationLog içine bir MutationEntry kaydeder.

AstWriter, bir MutationLog’u OVERLAY modunda yalnızca ekleme yapılan bir artımlı güncelleme olarak uygular: yeni overlay içerik akışları, güncellenmiş sayfa nesneleri, yalnızca yeni nesneleri kapsayan bir çapraz başvuru bölümü ve /Prev değeri önceki startxref’i işaret eden bir trailer. Orijinal baytlar, ISO 32000-2:2020, 7.5.6’nın artımlı güncelleme modeli uyarınca bozulmadan bırakılır. Updated girişleri için çizilen değiştirme metni, ISO 32000-2:2020, 7.3.4.2 uyarınca değişmez dizelerdeki \, ( ve ) karakterlerini kaçış karakterine alır.

AstPdfEmitter::emit(), yapı ağacı okumasının simetrik tersidir: okuyucu tarafından üretilen ağaçlar, düğüm kimliği yeniden numaralandırması ve belgelenmiş kanonikleştirme sınıfları dışında yapısal olarak eşdeğer ağaçlara gidip gelir. Düğümlerde bulunan MCID’ler, asla yeniden atanmadan birebir yeniden yayılır.

Uç durumlar ve arıza modları

• Şifrelenmiş girdi, herhangi bir ağaç işinden önce reddedilir; şifrelenmiş PDF’ler için kısmi ağaç sonucu yoktur. Önce şifreyi çözün.
• Kaynak tavanları: en çok düğüm (varsayılan 100,000), en çok derinlik (varsayılan 200), en çok bellek (varsayılan 256 MiB), gerçek zaman aşımı (varsayılan 30 s). Bir tavanı aşmak AstBuildLimitException fırlatır; zaman aşımı, bir alt sınıf olan AstBuildTimeoutException fırlatır.
• Sayfa aralığı 0 tabanlı ve dahildir; null sınırlar tüm sayfalar anlamına gelir.
• İçerik akışı ayrıştırılamayan bir sayfa, sınırlayıcı kutu eklenmesi sırasında atlanır; ağacın geri kalanı etkilenmez.
• AstCache::get() asla fırlatmaz: hatalı biçimlendirilmiş, kurcalanmış veya dize olmayan yükler null döndürür ve yeniden oluşturmaya zorlar. AstCache::set(), arka uç yazma veya anında geri okuma başarısız olduğunda yüksek sesle başarısız olur.
• AstMutator, düğüm kimliği bulunamadığında InvalidArgumentException fırlatır. Bilinmeyen güncelleme anahtarları sessizce yok sayılır; yalnızca text_content uygulanır.
• AstWriter::write(), girdide bir %PDF- başlığı veya bulunabilir bir startxref olmadığında AstWriteException fırlatır. Sınırlayıcı kutusu olmayan girişler sessizce atlanır. Nesne taramasıyla bulunamayan sayfalar — örneğin sıkıştırılmış çapraz başvuru akışları altında — atlanır; hiçbir overlay uygulanamazsa, girdi baytları değiştirilmeden döndürülür.
• OVERLAY çıktısı bir redaksiyon değildir. Beyaz dikdörtgen ve yeniden çizilen metin eklenir; orijinal içerik baytları dosyada kalır ve ham çıkarımla kurtarılabilir. Bunu GDPR Art. 17 silme işlemi veya yasal redaksiyon için kullanmayın. Kaynak ağaçta bir yeniden yapılandırma modu yazıcısı bulunur, ancak dahili olarak işaretlenmiştir, üretime hazır değildir ve desteklenen API yüzeyinin dışındadır.
• Overlay geometrisi, yazıcı sayfa MediaBox’ını okumadığı için A4 dikey (595 x 842 pt) varsayar. A4 olmayan sayfalarda overlay biraz yanlış hizalanabilir; çıktı yapısal olarak geçerli kalır.
• writeAndVerify() yalnızca yapıyı denetler: başlık, sondaki %%EOF ve çıktı büyümesi. Değiştirilen belgeyi semantik olarak yeniden ayrıştırmaz.
• AstPdfEmitter::emit(), kök bir Document düğümü olmadığında veya alt öğesi olmadığında AstEmitException fırlatır. OBJR (ek açıklama) eşlik girişleri bu sürümde yayılmaz.
• Bu modül hiçbir kriptografik işlem yapmaz ve hiçbir FIPS’e özgü davranış tanımlamaz. SHA-256 yalnızca önbellek anahtarları için içerik adresleme olarak görünür.

Uygunluk

Yapı ağacı yolu, ISO 32000-2 tarafından tanımlanan etiketli PDF mantıksal yapı olanaklarını okur; yazım sırasında mevcut olan RAG külliyatı mantıksal yapı hükümlerini içermez, bu nedenle bu ifade kaynak açıklamalarından ürün temellidir. Yazıcının artımlı güncelleme düzeni ISO 32000-2:2020, 7.5.6’yı (aşağıda alıntılanmıştır) izler ve değişmez dize kaçışı ISO 32000-2:2020, 7.3.4.2’yi (aşağıda alıntılanmıştır) izler.

Bu ifadeler, alıntılanan hükümlere karşı yeteneği açıklar. NextPDF hiçbir uygunluk sertifikasına sahip değildir ve bir hükmün desteklenmesi bir sertifika iddiası değildir.

Geliştirme notları

• Yüklenen her PdfReader için bir AstBuilder oluşturun. Ayrıştırmayı amorti etmek için derlemeler arasında bir AstCache yeniden kullanın; anahtar tasarımı, seçenek değişikliklerini kendiliğinden geçersiz kılar.
• Yazıcının tam olarak kaydedilen oturumu uygulaması için bir AstMutator ile AstWriter arasında bir MutationLog paylaşın. Bağımsız düzenleme oturumları arasında resetLog() çağırın.
• Düzen kaynaklı gruplama, yalın geri dönüş ağacına tercih edildiğinde etiketsiz belgeler için useHeuristic değerini true olarak ayarlayın.
• Derlemeler, özdeş baytlar ve seçenekler için belirlenimcidir; anlık görüntü tarzı testler için buna güvenin.
• Derleme başarısızlıklarını NextPDF\Pro\Ast\Exception hiyerarşisi aracılığıyla, yazma başarısızlıklarını NextPDF\Pro\Ast\Writer hiyerarşisi aracılığıyla yakalayın; ikisi, RuntimeException altında bir temeli paylaşmaz.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• AST — yetenek genel bakışı
• Projection — Derinlemesine başvuru
• Output Pipeline — Derinlemesine başvuru