Pro sürüm

AST

Bir bakışta

AST modülü, bir PDF’yi değişmez, gezinilebilir bir belge ağacına dönüştürür. Mevcut olduğunda etiketlenmiş-yapı ağacını kullanır ve etiketlenmemiş belgeler için sezgisel bir oluşturucuya geri döner; her düğüme sınırlayıcı kutular ve metin ekler.

Kullanılabilirlik ve lisanslama

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

Özellik başına bir lisans bayrağı yoktur. Kod, Pro sürümüyle sevk edilir; oluşturma davranışı, bir lisans anahtarıyla değil, tümüyle AstBuildOptions (kaynak sınırları ve sayfa aralıkları) ile yönetilir.

Kurulum

composer require nextpdf/pro:^3

Kod, NextPDF\Pro\Ast ad alanı altında yaşar.

Kavramsal genel bakış

AstBuilder, PDF’den ağaca işlem hattını düzenler: önbelleği denetle, şifrelenmiş girdiyi erken reddet, etiketlenmiş PDF’ler için yapı ağacını oku, aksi durumda etiketlenmemiş bir yola geri dön, içerik-akışı analizinden sınırlayıcı kutuları ekle, ardından sonucu önbelleğe al. Çıktı, düğümleri değişmez olan bir AstDocument’tır; güncellemeler, yerinde değiştirmek yerine etkilenen alt ağacı aşağıdan yukarıya yeniden oluşturur.

Etiketlenmemiş PDF’ler için iki yedek stratejisi vardır: çıplak bir yedek ve isteğe bağlı bir sezgisel oluşturucu (AstBuildOptions::$useHeuristic). Modül ayrıca, bir AST’yi bir PDF’ye geri yazabilen ve sonucu doğrulayabilen bir yayıcı yolu artı ağaca uygulanan değişiklikleri izlemek için bir mutasyon günlüğü sağlar.

Neden bu şekilde çalışıyor

Ağaç, yapısı gereği değişmezdir. Her düzenleme yalnızca etkilenen kök-düğüm yolunu yeniden oluşturur ve dokunulmamış alt ağaçları kimlik yoluyla paylaşır; böylece oluşturulmuş bir AstDocument, savunmacı kopyalar olmadan tutmak, önbelleğe almak ve eşzamanlı okuyuculara vermek için güvenlidir. Bu, bir PDF’nin diskte kendisinin nasıl değiştiğini yansıtır: geri-yazma yolu, dosyayı yeniden yazmak yerine AstWriter aracılığıyla artımlı bir güncelleme ekler; özgün baytları — ve mevcut imzaları — bozulmadan bırakır. Yalnızca-ekleme bir revizyon aynı zamanda yapısal olarak doğrulamak için ucuzdur; bu yüzden AstWriter, kendi çıktısını döndürmeden önce denetleyebilir. Yerinde değiştirmek yerine alt ağaçları yeniden oluşturmak, modülü hem gezinilebilir hem de güvenli bir şekilde düzenlenebilir kılan tek karardır.

Tasarım arka planı: Artımlı güncellemeler ve neden önemli oldukları.

Davranış sözleşmesi

AstBuilder::build($sourceHash), kaynak PDF’nin tam SHA-256 onaltılığını kabul eder ve bir AstDocument döndürür.
Şifrelenmiş PDF’ler, özel bir desteklenmeyen-şifreleme hatasıyla reddedilir; oluşturmadan önce şifresini çözün.
Hiçbir yapı ağacı mevcut olmadığında, oluşturucu etiketlenmemiş yolu otomatik olarak kullanır — etkinse sezgisel, aksi durumda çıplak yedek.
AstBuildOptions’taki kaynak sınırları (maksimum düğüm, maksimum derinlik, maksimum bellek, duvar-saati zaman aşımı), sınırsız iş yerine bir oluşturma-sınırı veya oluşturma-zaman-aşımı hatasına neden olur.
Önbellek anahtarı, kaynak karmasını ve seçenekler karmasını içerir; böylece özdeş girdiler ve seçeneklerle iki oluşturma aynı ağacı döndürür.
AstNode değişmezdir; tüketiciler, ağaç değiştiğinde yeni düğüm örnekleri alır.

Kod örneği — Hızlı başlangıç

Aşağıdaki, belgelenen genel API’yi yansıtır. Depo, bu modül için çalıştırılabilir bir örnek sevk etmez.

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

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

Kod örneği — Üretim

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.
}

Uç durumlar ve tuzaklar

İçerik akışı ayrıştırılamayan sayfalar, sınırlayıcı-kutu ekleme sırasında atlanır; ağaç yine de döndürülür, yalnızca o sayfalar için kutular olmadan.
Sezgisel oluşturucu isteğe bağlıdır. Devre dışı bırakıldığında, etiketlenmemiş PDF’ler çıplak yedekten daha kaba bir ağaç verir.
AstBuildOptions’taki sayfa aralığı, 0 tabanlı, kapsayıcı dizinler kullanır; her iki sınırı da null bırakmak tüm sayfaları işler.

Performans

Oluşturma maliyeti, düğüm sayısı ve sayfa sayısıyla ölçeklenir; AstBuildOptions her ikisini de sınırlar. Önbellek, aynı seçeneklerle aynı girdinin yinelenen oluşturmalarını kısa devre yapar. NextPDF burada sabit bir belge başına zamanlama yayımlamaz; duvar-saati zaman aşımı (varsayılan 30 sn) ve düğüm tavanı (varsayılan 100.000), en kötü durum işini sınırlar. Temsili belgelerle ölçün.

Güvenlik notları

Girdiyi güvenilmeyen olarak ele alın. Oluşturucu, şifrelenmiş PDF’leri kısmen işlemek yerine reddeder. Kaynak tavanları (düğümler, derinlik, bellek, zaman), patolojik veya düşmanca belgelere karşı korur. Bu modül hiçbir belge içeriğini günlüğe kaydetmez.

Uygunluk

Yapı-ağacı yolu, ISO 32000-2 tarafından tanımlanan etiketlenmiş-PDF yapılarını okur; modülün kaynağı, ilgili içerik-akışı ve yapı maddelerini açıklar. RAG bütüncesi yazım zamanında kullanılamadığı için bu sayfa hiçbir harici madde tanımlayıcısı ileri sürmez ve uygunluk beyanlarını modülün testleriyle doğrulanan davranışla sınırlar.

Enterprise sınır notu

Enterprise, AST davranışını değiştirmez. Enterprise, ayrıca belgelenen daha yüksek katmanlı uyumluluk ve arşivleme yetenekleri ekler; bunlar bir AST oluşturmak veya tüketmek için gerekli değildir.

Core yedeği / alternatifi

Pro olmadan, eşdeğer bir belge ağacı yoktur; çağıranlar içerik akışlarını NextPDF Core ilkellerini kullanarak doğrudan ayrıştırır. /modules/ast/ sayfasına bakın.

Yayımlama sınırı

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