Ast: anlamsal belge ağacı ve serileştirme

Bir bakışta

Ast modülü, motorun anlamsal belge soyut sözdizimi ağacını (AST) sunar. Bir belgeyi türlenmiş bir düğüm hiyerarşisi olarak modeller: Document, Section, Heading, Paragraph, List, Table, Figure, Code ve FormField. Model, sınırlayıcı kutuları ve alıntı çapalarını kaydeder ve sürümlenmiş JavaScript Object Notation (JSON) biçimine serileştirir. Erişilebilirlik etiketleme katmanı, yapı ağacı üretmek için bu ağacı kullanır.

Kararlılık: deneysel. Bu, dahili bir model yüzeyidir. Sınıfları sürüm sabitlemeli genel API garantileri sunmaz. Düğüm kümesi ve düğüm öznitelikleri değişebilir. Serileştirme şeması bağımsız olarak sürümlenir (AstDocument::CURRENT_SCHEMA_VERSION = '1.0.0'). Serileştirici, uyumsuz bir şemayı algılar ve reddeder; böylece kalıcılaştırılan AST JSON’ı, bellek içi API değişse bile kararlı bir sözleşmeyi korur.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Burada AST, bir belgenin mantıksal yapısını temsil eder. Tek bir girdi biçimine yönelik ayrıştırıcı sözdizim ağacı değildir. AstDocument kapsayıcıdır. Kök AstNode düğümünü (NodeType::Document olmak zorundadır), bir şema sürümünü, kaynak Portable Document Format (PDF) dosyasının karmasını ve sayfa sayısını barındırır. Boş bir şema sürümü, birden küçük sayfa sayısı veya yanlış kök türü dahil olmak üzere geçersiz yapılandırmaları reddeder.

AstNode özyinelemeli düğümdür. NodeType anlamsal türleri sıralar. Bir düğüm; alt öğeler, isteğe bağlı bir BoundingBox, isteğe bağlı metin içeriği ve NodeAttributeSchema tarafından doğrulanan öznitelikler taşır. Düğüm API’si değiştirilemez türetmeyi destekler. withBboxAndText() yeni bir düğüm döndürür. deepClone() bir alt ağacı kopyalar. NodeId, kimliği temsil eden değer nesnesidir. CitationAnchor, izlenebilirlik için bir düğümü kaynak konumuna bağlar. AstNodeCollection, Countable/IteratorAggregate arabirimlerini uygulayan ve ofType() ile filtreleme sağlayan bir kümedir.

AstSerializer kalıcılık sınırıdır. serialize() bir AstDocument nesnesini JSON’a yazar. deserialize() onu geri okur. canDeserialize() ve extractSchemaVersion() ayrıştırmadan önce uyumluluğu denetlemenize olanak tanır; böylece şema uyumsuzluğu, bozuk bir yükleme yerine algılanmış bir durum olur. AstDocument::estimateTokenCount() içeriği, akış aşağıdaki belirteç sınırlı işleme için boyutlandırmaya yardımcı olur.

API yüzeyi

Sınıf	Önemli üyeler	Rol
AstDocument	toJson(), nodeCount(), estimateTokenCount(), CURRENT_SCHEMA_VERSION	Kök kapsayıcı; kök türünü ve şemayı doğrular
AstNode	addChild(), children(), childCount(), totalNodeCount(), withBboxAndText(), deepClone()	Özyinelemeli anlamsal düğüm
NodeType (enum)	Document, Heading, Table, Figure, FormField, …	Anlamsal düğüm türü
AstNodeCollection	add(), count(), isEmpty(), ofType(), toArray()	Yinelenebilir, türe göre filtrelenebilir düğüm kümesi
AstSerializer	serialize(), deserialize(), canDeserialize(), extractSchemaVersion()	Sürümlenmiş JSON kalıcılığı
BoundingBox	toArray(), equals()	Geometri değer nesnesi (epsilon karşılaştırması)
NodeId / CitationAnchor	toString(), equals(), toArray()	Düğüm kimliği ve kaynak izlenebilirliği çapası
NodeAttributeSchema	öznitelik doğrulaması	Düğüm öznitelikleri için şema

Tam PHPDoc tablosunu oluşturmak için composer docs:generate-api-php -- --module=Ast komutunu çalıştırın.

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

Küçük bir ağaç oluşturun, ardından onu serileştirin.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Ast\AstNode;
use NextPDF\Ast\AstSerializer;
use NextPDF\Ast\NodeType;

$root = new AstNode(NodeType::Document);
$heading = new AstNode(NodeType::Heading);
$root->addChild($heading);
$root->addChild(new AstNode(NodeType::Paragraph));

echo "Nodes: {$root->totalNodeCount()}\n";

$json = (new AstSerializer())->serialize(/* an AstDocument wrapping $root */);

Kod örneği — üretim

Kalıcılaştırılan AST’yi savunmacı biçimde serileştirip geri okuyun. Güvenilmeyen JSON’ı geri okumadan önce şema uyumluluğunu denetleyin.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Ast\AstDocument;
use NextPDF\Ast\AstSerializer;
use Psr\Log\LoggerInterface;

final readonly class AstStore
{
    public function __construct(
        private AstSerializer $serializer,
        private LoggerInterface $logger,
    ) {}

    public function load(string $json): ?AstDocument
    {
        if (!$this->serializer->canDeserialize($json)) {
            $this->logger->warning('AST JSON schema incompatible; rejected.', [
                'found_schema' => $this->serializer->extractSchemaVersion($json),
                'expected'     => AstDocument::CURRENT_SCHEMA_VERSION,
            ]);

            return null;
        }

        return $this->serializer->deserialize($json);
    }
}

Uç durumlar & tuzaklar

• AstDocument kök düğümün NodeType::Document olmasını gerektirir. Başka bir kök içeren ağaç, yapılandırma sırasında özel durum fırlatır.
• AstNode::withBboxAndText() ve deepClone() yeni örnekler döndürür. Kullanılabilir düğüm değiştiricileri (addChild()) düğümü yerinde değiştirir. Türetme yardımcıları değiştirmez. Hangi yöntemi çağırdığınızı bilin.
• Dışarıdan gelen JSON için deserialize() çağrısını her zaman canDeserialize() ile koruyun. Bir şema sürümü uyumsuzluğu, algılanabilir ve beklenen bir durumdur.
• estimateTokenCount() akış aşağıdaki işlemeyi boyutlandırmaya yönelik bir tahmindir, kesin bir belirteç sayımı değildir. Bunu yetkili bir değer olarak görmeyin.
• BoundingBox::equals() bir epsilon karşılaştırmasıdır (varsayılan 0.001). Kesin kayan nokta eşitliği bir sözleşme değildir.

Performans

Ağaç oluşturma ve dolaşma, düğüm sayısında O(n)‘dir. Serileştirme, ağaç boyutunda doğrusaldır. Yeniden üretilebilirlik profili bitwise şeklindedir. Aynı ağaç aynı JSON baytlarına serileştirilir; bu da şemayı bir kalıcılık sözleşmesi olarak kararlı tutar. Varsayılan referans iş yükü, 1500 ms duvar süresi / 64 MB tepe bellek bütçesinin oldukça içinde kalır.

Güvenlik notları

AstSerializer::deserialize() kalıcılaştırılabilen veya iletilebilen JSON’ı ayrıştırır. Uyumluluğu önce canDeserialize() ile doğrulayın. Serileştirilmiş ağacın metin içeriğini ve özniteliklerini, uygulamaya yeniden girdiklerinde veya işlendiklerinde güvenilmeyen dizeler olarak ele alın. Modülün kendisi herhangi bir input/output (I/O) gerçekleştirmez ve harici veri gömmez. Motorun tehdit modeli için /modules/core/security/ sayfasına bakın.

Uyumluluk

Bu modül, herhangi bir PDF belirtimine ilişkin normatif iddiada bulunmaz. Anlamsal AST, motor içi bir soyutlamadır. Maddelerine atıfta bulunulması gereken standartlaştırılmış bir belge modeli uygulamaz. AST’nin erişilebilirlik etiketlemesini beslediği yerlerde, çıktının PDF/UA ve etiketli PDF uyumluluğu burada değil, /modules/core/accessibility/ ve /modules/core/conformance/ sayfalarında belgelenir ve doğrulanır.

Ayrıca bakınız

• Erişilebilirlik modülü — yapı ağacını oluşturmak için AST’yi kullanır.
• İnceleme modülü — yerleşimi ve yapıyı inceler.
• HTML modülü — belge yapısının bir kaynağını sağlar.
• Uyumluluk genel bakışı