AST

لمحة سريعة

تحوّل وحدة ⁨AST⁩ ملف ⁨PDF⁩ إلى شجرة مستند ثابتة قابلة للتنقّل. تستخدم شجرة البنية الموسومة عند حضورها وتتراجع إلى بانٍ ارتدادي (heuristic) للمستندات غير الموسومة، مُرفِقةً مربّعات إحاطة ونصًا بكل عقدة.

التوفّر والترخيص

تُشحن هذه القدرة في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمظروف ترخيص من فئة ⁨Pro⁩. لا يُحمّل أي نشر يفتقر إلى هذا الاستحقاق أصناف هذه القدرة. قارِن الإصدارات واحصل على ترخيص.

لا يوجد علم ترخيص منفصل لكل ميزة. تُشحن الشيفرة مع إصدار ⁨Pro⁩؛ ويُحكَم سلوك البناء بالكامل عبر AstBuildOptions (حدود الموارد ومديات الصفحات)، لا مفتاح ترخيص.

التثبيت

composer require nextpdf/pro:^3

تعيش الشيفرة تحت فضاء الاسم NextPDF\Pro\Ast.

نظرة مفاهيمية عامة

يُنسِّق AstBuilder مسار التحويل من ⁨PDF⁩ إلى شجرة: افحص ذاكرة التخزين المؤقت، وارفض المُدخَل المُشفَّر مبكرًا، واقرأ شجرة البنية للمستندات الموسومة، وتراجَع إلى مسار غير موسوم خلاف ذلك، وأرفِق مربّعات الإحاطة من تحليل دفق المحتوى، ثم خزّن النتيجة مؤقتًا. المُخرَج هو AstDocument عُقَده ثابتة؛ وتعيد التحديثات بناء الشجرة الفرعية المتأثّرة من الأسفل إلى الأعلى بدلًا من التعديل في موضعها.

توجد استراتيجيتا تراجع للمستندات غير الموسومة: تراجع مجرّد وبانٍ ارتدادي اختياري (AstBuildOptions::$useHeuristic). توفّر الوحدة أيضًا مسار باعث يمكنه كتابة ⁨AST⁩ عودًا إلى ⁨PDF⁩ والتحقّق من النتيجة، إضافةً إلى سجل تحوّل لتتبّع التغييرات المُطبَّقة على الشجرة.

لماذا يعمل بهذه الطريقة

الشجرة ثابتة بحكم البناء. يعيد كل تعديل بناء مسار الجذر-إلى-العقدة المتأثّر فقط، ويشارك الأشجار الفرعية غير المُتغيّرة بالهُوية، فيكون AstDocument المبنيّ آمنًا للاحتفاظ به وتخزينه مؤقتًا وتسليمه لقُرّاء متزامنين دون نسخ دفاعية. يعكس هذا كيفية تغيّر ⁨PDF⁩ ذاته على القرص: يُلحِق مسار الكتابة-عودًا تحديثًا تزايديًا عبر AstWriter بدلًا من إعادة كتابة الملف، مُبقيًا البايتات الأصلية — وأي تواقيع موجودة — سليمة. ومراجعة مُلحَقة-فقط رخيصة التحقّق بنيويًا أيضًا، ولهذا يستطيع AstWriter فحص مُخرَجه بنفسه قبل إرجاعه. إعادة بناء الأشجار الفرعية بدلًا من التعديل في الموضع هي القرار الوحيد الذي يجعل الوحدة قابلة للتنقّل وقابلة للتحرير بأمان معًا.

خلفية التصميم: التحديثات التزايدية ولماذا تهمّ.

عقد السلوك

• يقبل AstBuilder::build($sourceHash) كامل ⁨SHA-256⁩ السداسي عشري لمصدر ⁨PDF⁩ ويُعيد AstDocument.
• تُرفض ملفات ⁨PDF⁩ المُشفَّرة بخطأ تشفير-غير-مدعوم مُخصَّص؛ فُكّ التشفير قبل البناء.
• عند غياب أي شجرة بنية، يستخدم الباني مسار غير الموسوم تلقائيًا — ارتداديًا إن فُعِّل، وتراجعًا مجرّدًا خلاف ذلك.
• تسبّب حدود الموارد في AstBuildOptions (أقصى عُقَد، وأقصى عمق، وأقصى ذاكرة، ومهلة زمن جداري) خطأ حدّ-بناء أو مهلة-بناء بدلًا من عمل غير محدود.
• يدمج مفتاح ذاكرة التخزين المؤقت تجزئة المصدر وتجزئة الخيارات، فيُعيد بناءان بمُدخَلات وخيارات متطابقة الشجرة نفسها.
• ‏AstNode ثابت؛ ويتلقّى المستهلكون نُسخ عُقَد جديدة عند تغيّر الشجرة.

مثال برمجي — بداية سريعة

يعكس ما يلي الـ ⁨API⁩ العام الموثَّق. لا يشحن المستودع مثالًا قابلًا للتشغيل لهذه الوحدة.

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

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

مثال برمجي — إنتاج

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

الحالات الحدّية والمزالق

• تُتخطّى الصفحات التي يتعذّر تحليل دفق محتواها أثناء إرفاق مربّع الإحاطة؛ ولا تزال الشجرة تُعاد، فقط دون مربّعات لتلك الصفحات.
• الباني الارتدادي اشتراكي. ومع تعطيله، تُنتج المستندات غير الموسومة شجرة أخشن من التراجع المجرّد.
• يستخدم مدى الصفحات في AstBuildOptions فهارس صفرية الأساس وشاملة؛ وترك الحدّين كليهما null يعالج كل الصفحات.

الأداء

تتناسب تكلفة البناء مع عدد العُقَد وعدد الصفحات؛ ويحدّ AstBuildOptions كليهما. تقصُر ذاكرة التخزين المؤقت عمليات البناء المتكرّرة للمُدخَل نفسه بالخيارات نفسها. لا ينشر ⁨NextPDF⁩ هنا توقيتًا ثابتًا لكل مستند؛ وتحدّ مهلة الزمن الجداري (افتراضيًا 30 ثانية) وسقف العُقَد (افتراضيًا 100,000) أسوأ حالات العمل. قِس بمستندات تمثيلية.

ملاحظات أمنية

عامِل المُدخَل كغير موثوق. يرفض الباني ملفات ⁨PDF⁩ المُشفَّرة بدلًا من معالجتها جزئيًا. تحمي سقوف الموارد (العُقَد، والعمق، والذاكرة، والوقت) من المستندات المرضية أو العدائية. ولا تسجّل هذه الوحدة أي محتوى مستند.

المطابقة

يقرأ مسار شجرة البنية بُنى ⁨PDF⁩ الموسومة المُعرَّفة في ⁨ISO 32000-2⁩؛ ويُعلِّق مصدر الوحدة على بنود دفق المحتوى والبنية ذات الصلة. ولأن مادة ⁨RAG⁩ لم تتوفّر وقت التأليف، لا تؤكّد هذه الصفحة أي معرّفات بنود خارجية وتحصر بيانات المطابقة في السلوك المُتحقَّق منه باختبارات الوحدة.

ملاحظة حدود ⁨Enterprise⁩

لا يغيّر ⁨Enterprise⁩ سلوك ⁨AST⁩. يضيف ⁨Enterprise⁩ قدرات أعلى مستوى للامتثال والأرشفة موثَّقة على حِدة؛ وهي غير مطلوبة لبناء ⁨AST⁩ أو استهلاكها.

احتياط / بديل ⁨Core⁩

بدون ⁨Pro⁩، لا توجد شجرة مستند مكافئة؛ ويحلّل المستدعون أدفاق المحتوى مباشرةً باستخدام بدائيات ⁨NextPDF Core⁩. راجع /modules/ast/.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح الـ ⁨API⁩ العام المدعوم فقط. أما مسارات فضاءات الأسماء الداخلية، والأصناف المساعِدة، وجداول الآليات، وأسماء ملفات أدلة التشغيل، وبادئات التذاكر فخارج النطاق.

انظر أيضًا

• ‏⁨AST⁩ — مرجع معمّق
• الإسقاط
• المقارنة
• مسار الإخراج