AST — مرجع متعمّق

نظرة سريعة

هذه الصفحة هي المرجع المتعمّق لوحدة AST في Pro. تغطّي واجهات البناء والتخزين المؤقت والتعديل والكتابة والإصدار العامة، وعقود سلوكها، وأنماط أعطالها. تحلّل الوحدة ملف ⁨PDF⁩ مُحمَّلًا إلى شجرة ⁨AstDocument⁩ غير قابلة للتغيير، وتطبّق تعديلات مُسجَّلة في الذاكرة، وتكتب تحديثات تزايدية قائمة على التراكب. ⁨AstDocument⁩ و⁨AstNode⁩ هما نوعا قيمة من Core في نطاق الأسماء ⁨NextPDF\Ast⁩؛ وتنتج هذه الوحدة كليهما وتستهلكهما.

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

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

لا توجد راية ترخيص لكل ميزة. هذه قدرة من إصدار Pro. يُحكَم سلوك البناء بالكامل بواسطة ⁨AstBuildOptions⁩.

واجهة ⁨API⁩ العامة

الرمز	المعاملات	السلوك الافتراضي	يُرجِع	يرمي أو يفشل بـ	ملاحظات
AstBuilder::__construct	PdfReader $reader، AstBuildOptions $options، ?AstCache $cache = null	يربط قارئًا مُحمَّلًا بخيارات البناء؛ التخزين المؤقت اختياري	AstBuilder	—	التخزين المؤقت الفارغ (null) يعني أن كل استدعاء لـ ⁨build()⁩ يُعيد البناء.
AstBuilder::build	string $sourceHash (قيمة SHA-256 الست عشرية الكاملة لبايتات الـ PDF)	البحث في التخزين المؤقت، ورفض التشفير، ومسار شجرة البنية، والرجوع إلى المسار غير الموسوم، وإرفاق المربع المُحيط، والتخزين المؤقت	AstDocument	AstUnsupportedEncryptionException، AstBuildLimitException، AstBuildTimeoutException	إصابة التخزين المؤقت تُرجِع دون إعادة تحليل.
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	كائن قيمة إعداد غير قابل للتغيير	AstBuildOptions	—	⁨estimatedTokenBudget⁩ تلميح إعلامي؛ وهو غير مُنفَّذ.
AstBuildOptions::pageRangeContains	int $pageIndex	صحيح عندما يقع الفهرس المُصفَّر داخل النطاق المُعَدّ	bool	—	الحدود الفارغة (null) مفتوحة النهاية؛ وكون كليهما فارغًا يعني جميع الصفحات.
AstBuildOptions::hash	—	قيمة SHA-256 ثابتة على جميع قيم الخيارات	string	—	القيم المتساوية تُنتِج قيم تجزئة متساوية عبر النسخ؛ تُستخدَم مقطعًا لمفتاح التخزين المؤقت.
AstCache::__construct	CacheInterface $backend	يغلّف أي خلفية PSR-16	AstCache	—	—
AstCache::buildKey	string $sourceHash، AstBuildOptions $options	المفتاح = nextpdf_ast_v1_ + أول 32 خانة ست عشرية من تجزئة المصدر + _ + أول 16 خانة ست عشرية من تجزئة الخيارات	string	—	تغييرات الخيارات تُبطِل النتائج المخزَّنة تلقائيًا.
AstCache::get	string $cacheKey	يفك ترميز حمولة JSON عبر تحقّق صارم لكل حقل	?AstDocument	لا يرمي أبدًا؛ الإخفاقات تُرجِع null	الحمولات المُشوَّهة أو المُتلاعَب بها تفشل بأمان بوصفها إخفاق تخزين مؤقت.
AstCache::set	string $cacheKey، AstDocument $document	يخزّن JSON مع مهلة صلاحية (TTL) قدرها 24 ساعة، ثم يتحقّق بقراءة فورية مرتدّة	void	AstWriteVerificationException (نطاق أسماء Exception)	فشل كتابة الخلفية أو فشل الرحلة الذهاب-إياب يرفع الاستثناء.
AstCache::delete	string $cacheKey	إزالة بأفضل جهد	void	لا يرمي أبدًا	إخفاقات حذف الخلفية تُبتلَع.
AstCache::has	string $cacheKey	فحص وجود بأفضل جهد	bool	لا يرمي أبدًا؛ الإخفاقات تُرجِع false	—
AstMutator::updateNode	AstDocument $document، string $nodeId، array $updates	يستبدل text_content، ويسجّل مُدخَل Updated	AstDocument (نسخة جديدة)	InvalidArgumentException	يُطبَّق مفتاح text_content فقط؛ والمفاتيح غير المعروفة تُتجاهَل.
AstMutator::deleteNode	AstDocument $document، string $nodeId	يزيل العقدة من الشجرة في الذاكرة، ويسجّل مُدخَل Deleted	AstDocument (نسخة جديدة)	InvalidArgumentException	إزالة في الذاكرة فقط؛ راجع تنبيه التنقيح أدناه.
AstMutator::getMutationLog	—	يُرجِع نسخة السجلّ المشتركة	MutationLog	—	مرّر السجلّ نفسه إلى ⁨AstWriter⁩.
AstMutator::resetLog	—	يتجاهل جميع التعديلات المُسجَّلة	void	—	يبدأ سجلًّا جديدًا.
MutationLog	record، all، isEmpty، count، forNode، mutatedNodeIds	سجلّ في الذاكرة يُلحَق فقط، مع الحفاظ على ترتيب الإدراج	حسب كل دالّة	—	⁨forNode⁩ تُرجِع أحدث مُدخَل لعقدة؛ المُدخَل الأخير هو الغالب.
MutationEntry::__construct	string $nodeId، MutationType $type، ?AstNode $originalNode، ?AstNode $mutatedNode، DateTimeImmutable $timestamp	سجلّ غير قابل للتغيير لتعديل واحد	MutationEntry	—	⁨originalNode⁩ فارغ (null) في حالة Inserted؛ و⁨mutatedNode⁩ فارغ (null) في حالة Deleted.
MutationType	حالات التعداد Updated، Inserted، Deleted	تصنيف مدعوم بسلسلة نصية	—	—	⁨Deleted⁩ في وضع OVERLAY يُخفي المحتوى؛ ولا يمحو البايتات.
AstWriter::write	string $originalPdfBytes، MutationLog $log	يُلحِق تحديثًا تزايديًا تغطّي تدفقات تراكبه المربعاتِ المُحيطة المُعدَّلة	string (بايتات PDF المُعدَّلة)	AstWriteException	السجلّ الفارغ يُرجِع المُدخَل دون تغيير. مُدخَلات Inserted والمُدخَلات دون مربع مُحيط تُتخطّى.
AstWriter::writeAndVerify	string $originalPdfBytes، MutationLog $log	يشغّل write()، ثم فحصًا بنيويًا للمُخرَج	string (بايتات PDF مُتحقَّق منها)	AstWriteException، AstWriteVerificationException (نطاق أسماء Writer)	التحقّق بنيوي، وليس دلاليًا.
AstPdfEmitter::emit	AstNode $root، BinaryBuffer $buffer، ObjectRegistry $registry، array $pageObjects	يكتب StructTreeRoot وسلسلة StructElem وParentTree للشجرة المُعطاة	EmitResult	AstEmitException	يجب أن يكون الجذر عقدة Document ذات أبناء. مُصدِر ذهاب-إياب للتحقّق من شجرة البنية.
EmitResult::__construct	int $structTreeRootObject، int $rootElementObject، int $parentTreeObject، int $elementObjectCount، int $parentTreeNextKey	سجلّ غير قابل للتغيير لمُعرِّفات الكائنات المُصدَرة	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

تسلسل الاستثناءات الهرمي

• ⁨NextPDF\Pro\Ast\Exception\AstException⁩ يمتدّ من ⁨RuntimeException⁩ — أساس تسلسل البناء الهرمي.
• ⁨AstBuildLimitException⁩ يمتدّ من ⁨AstException⁩ — تجاوُز سقف العقد أو العمق أو الذاكرة.
• ⁨AstBuildTimeoutException⁩ يمتدّ من ⁨AstBuildLimitException⁩ — انقضاء مهلة البناء بزمن الساعة.
• ⁨AstNoStructTreeException⁩ يمتدّ من ⁨AstException⁩ — لا توجد شجرة بنية. يلتقطه ⁨AstBuilder::build()⁩ داخليًا ويرجع إلى البديل؛ ولا يلاحظه مستدعو ⁨build()⁩.
• ⁨AstUnsupportedEncryptionException⁩ يمتدّ من ⁨AstException⁩ — ملف الـ ⁨PDF⁩ المُدخَل مُشفَّر.
• ⁨NextPDF\Pro\Ast\Exception\AstWriteVerificationException⁩ يمتدّ من ⁨AstException⁩ — فشل التحقّق من كتابة التخزين المؤقت.
• ⁨NextPDF\Pro\Ast\Writer\AstWriteException⁩ يمتدّ من ⁨RuntimeException⁩ — فشل في مُدخَل الكاتب أو بنيته.
• ⁨NextPDF\Pro\Ast\Writer\AstWriteVerificationException⁩ يمتدّ من ⁨AstWriteException⁩ — فشل التحقّق البنيوي بعد الكتابة.

يوجد صنفان متمايزان باسم ⁨AstWriteVerificationException⁩ في نطاقَي أسماء مختلفين. يرفع ⁨AstCache::set()⁩ الصنف من نطاق أسماء ⁨Exception⁩؛ ويرفع ⁨AstWriter::writeAndVerify()⁩ الصنف من نطاق أسماء ⁨Writer⁩. طابِق نطاق الأسماء في جُمل ⁨catch⁩.

عقد السلوك

يتطلّب ⁨AstBuilder::build($sourceHash)⁩ قيمة SHA-256 الست عشرية الكاملة لبايتات المصدر. المسار هو: بحث اختياري في التخزين المؤقت، ورفض التشفير، ومسار شجرة البنية، والرجوع إلى المسار غير الموسوم، وإرفاق المربع المُحيط، وتخزين مؤقت اختياري.

يجمع مفتاح التخزين المؤقت بين تجزئة المصدر وتجزئة ⁨AstBuildOptions⁩. تجزئة الخيارات ثابتة عبر النسخ ذات القيم المتطابقة، لذا تُرجِع المُدخَلات والخيارات المتطابقة الشجرةَ نفسها. حين لا يُوفَّر تخزين مؤقت، يُعيد كل استدعاء البناء. الحمولات المخزَّنة هي ⁨JSON⁩، وليست تسلسل ⁨PHP⁩ الأصلي على الإطلاق: يتحقّق مسار القراءة من كل حقل ويُنشئ أنواع قيمة AST فقط، لذا لا يمكن لمُدخَل تخزين مؤقت مسموم أن يُحفِّز حقن كائنات، ويتدنّى إلى إخفاق تخزين مؤقت.

يعمل مسار شجرة البنية عند وجود شجرة بنية. تُنفَّذ سقوف الموارد — عدد العقد والعمق ودلتا الذاكرة وزمن الساعة — أثناء قراءة شجرة البنية وترفع ⁨AstBuildLimitException⁩ أو ⁨AstBuildTimeoutException⁩. إذا أبلغ القارئ عن غياب شجرة البنية، يتحوّل الباني إلى المسار غير الموسوم: الباني الاستدلالي عندما تكون ⁨useHeuristic⁩ صحيحة، وإلا فالباني البديل المُجرَّد. تُرفَق المربعات المُحيطة بتحليل تدفق محتوى كل صفحة ضمن النطاق؛ والصفحة التي يتعذّر تحليل تدفق محتواها تُتخطّى وتترك بقية الشجرة سليمة.

⁨AstNode⁩ غير قابلة للتغيير. تحديثات الشجرة تُعيد بناء العقد المتأثّرة من الأسفل إلى الأعلى؛ وتُرجَع الشُّجيرات غير المتغيّرة بالهوية. يتّبع ⁨AstMutator⁩ العقد نفسه: كل تعديل يُرجِع ⁨AstDocument⁩ جديدًا، ويُعيد بناء المسار من الجذر إلى الهدف فقط، ويسجّل ⁨MutationEntry⁩ في ⁨MutationLog⁩ المشترك.

يطبّق ⁨AstWriter⁩ سجلَّ ⁨MutationLog⁩ في وضع OVERLAY بوصفه تحديثًا تزايديًا يُلحَق فقط: تدفقات محتوى تراكب جديدة، وكائنات صفحات مُحدَّثة، وقسم مرجعية متقاطعة يغطّي الكائنات الجديدة فقط، ومقطورة يشير ⁨/Prev⁩ فيها إلى ⁨startxref⁩ السابق. تُترَك البايتات الأصلية سليمة، وفقًا لنموذج التحديث التزايدي في ⁨ISO 32000-2⁩:2020، 7.5.6. النص البديل المرسوم لمُدخَلات ⁨Updated⁩ يهرّب ⁨\⁩ و⁨(⁩ و⁨)⁩ في السلاسل الحرفية، وفقًا لـ ⁨ISO 32000-2⁩:2020، 7.3.4.2.

⁨AstPdfEmitter::emit()⁩ هو النظير العكسي المتماثل لقراءة شجرة البنية: الأشجار التي يُنتِجها القارئ تعود ذهابًا-إيابًا إلى أشجار مكافئة بنيويًا، باستثناء إعادة ترقيم مُعرِّفات العقد وأصناف التقنين الموثَّقة. تُعاد قيم MCID الموجودة على العقد كما هي حرفيًا، ولا يُعاد تخصيصها أبدًا.

الحالات الحدّية وأنماط الأعطال

• يُرفَض المُدخَل المُشفَّر قبل أي عمل على الشجرة؛ ولا توجد نتيجة شجرة جزئية لملفات ⁨PDF⁩ المُشفَّرة. فُكّ التشفير أولًا.
• سقوف الموارد: أقصى عدد للعقد (الافتراضي 100,000)، وأقصى عمق (الافتراضي 200)، وأقصى ذاكرة (الافتراضي 256 MiB)، ومهلة زمن الساعة (الافتراضي 30 ثانية). تجاوُز أي سقف يرفع ⁨AstBuildLimitException⁩؛ والمهلة ترفع ⁨AstBuildTimeoutException⁩، وهو صنف فرعي.
• نطاق الصفحات مُصفَّر وشامل؛ والحدود الفارغة (null) تعني جميع الصفحات.
• الصفحة التي يتعذّر تحليل تدفق محتواها تُتخطّى أثناء إرفاق المربع المُحيط؛ ولا تتأثّر بقية الشجرة.
• ⁨AstCache::get()⁩ لا يرمي أبدًا: الحمولات المُشوَّهة أو المُتلاعَب بها أو غير النصية تُرجِع null وتفرض إعادة البناء. ⁨AstCache::set()⁩ يفشل بصخب حين تفشل كتابة الخلفية أو القراءة الفورية المرتدّة.
• يرفع ⁨AstMutator⁩ استثناء ⁨InvalidArgumentException⁩ عندما لا يُعثَر على مُعرِّف العقدة. مفاتيح التحديث غير المعروفة تُتجاهَل بصمت؛ ويُطبَّق ⁨text_content⁩ فقط.
• يرفع ⁨AstWriter::write()⁩ استثناء ⁨AstWriteException⁩ عندما يفتقر المُدخَل إلى ترويسة ⁨%PDF-⁩ أو إلى ⁨startxref⁩ يمكن تحديد موضعه. المُدخَلات دون مربع مُحيط تُتخطّى بصمت. الصفحات التي يتعذّر تحديد موضعها بمسح الكائنات — مثلًا تحت تدفقات المرجعية المتقاطعة المضغوطة — تُتخطّى؛ وإذا تعذّر تطبيق أي تراكب، تُرجَع بايتات المُدخَل دون تغيير.
• مُخرَج OVERLAY ليس تنقيحًا. يُلحَق المستطيل الأبيض والنص المُعاد رسمه؛ وتبقى بايتات المحتوى الأصلي في الملف ويمكن استرجاعها بالاستخلاص الخام. لا تستخدمه لمحو المادة 17 من GDPR ولا للتنقيح القانوني. يوجد كاتب بوضع إعادة البناء في شجرة المصدر لكنه مُعلَّم داخليًا، وغير جاهز للإنتاج، وخارج واجهة ⁨API⁩ المدعومة.
• تفترض هندسة التراكب توجّه A4 عموديًا (595 × 842 نقطة) لأن الكاتب لا يقرأ ⁨MediaBox⁩ الصفحة. على صفحات غير A4 قد يكون التراكب مُنحرِفًا قليلًا؛ ويبقى المُخرَج صالحًا بنيويًا.
• يفحص ⁨writeAndVerify()⁩ البنية فقط: الترويسة، و⁨%%EOF⁩ الختامية، ونموّ المُخرَج. ولا يُعيد تحليل المستند المُعدَّل دلاليًا.
• يرفع ⁨AstPdfEmitter::emit()⁩ استثناء ⁨AstEmitException⁩ عندما لا يكون الجذر عقدة Document أو حين لا يكون له أبناء. مُدخَلات OBJR (التعليقات التوضيحية) المرافِقة لا تُصدَر في هذا الإصدار.
• لا تُجري هذه الوحدة أي عمليات تعمية، ولا تُعرِّف أي سلوك خاص بـ FIPS. يظهر SHA-256 فقط بوصفه عنونة محتوى لمفاتيح التخزين المؤقت.

المطابقة

يقرأ مسار شجرة البنية مرافقَ البنية المنطقية لملفات ⁨PDF⁩ الموسومة المُعرَّفة في ⁨ISO 32000-2⁩؛ ومجموعة RAG المتاحة وقت التأليف لا تتضمّن بنود البنية المنطقية، لذا فتلك العبارة مُؤسَّسة على المُنتَج انطلاقًا من تعليقات المصدر. يتّبع تخطيط التحديث التزايدي للكاتب ⁨ISO 32000-2⁩:2020، ⁨7.5.6⁩ (مُستشهَد به أدناه)، ويتّبع تهريبه للسلاسل الحرفية ⁨ISO 32000-2⁩:2020، 7.3.4.2 (مُستشهَد به أدناه).

تصف هذه العبارات القدرة إزاء البنود المُستشهَد بها. لا تحمل ⁨NextPDF⁩ أي شهادة مطابقة، ودعم بند ما ليس ادعاء شهادة.

ملاحظات التطوير

• كوِّن ⁨AstBuilder⁩ واحدًا لكل ⁨PdfReader⁩ مُحمَّل. أعِد استخدام ⁨AstCache⁩ عبر عمليات البناء لتوزيع كلفة التحليل؛ فتصميم المفتاح يجعل تغييرات الخيارات ذاتية الإبطال.
• شارِك ⁨MutationLog⁩ واحدًا بين ⁨AstMutator⁩ و⁨AstWriter⁩ ليطبّق الكاتب الجلسة المُسجَّلة تمامًا. استدعِ ⁨resetLog()⁩ بين جلسات التحرير المستقلّة.
• اضبط ⁨useHeuristic⁩ على صحيح للمستندات غير الموسومة عندما يكون التجميع المُشتَقّ من التخطيط أفضل من شجرة البديل المُجرَّدة.
• عمليات البناء حتمية للبايتات والخيارات المتطابقة؛ اعتمِد على ذلك لاختبارات نمط اللقطات (snapshot).
• التقِط إخفاقات البناء عبر تسلسل ⁨NextPDF\Pro\Ast\Exception⁩ الهرمي وإخفاقات الكتابة عبر تسلسل ⁨NextPDF\Pro\Ast\Writer⁩ الهرمي؛ فالاثنان لا يتشاركان أساسًا دون ⁨RuntimeException⁩.

حدود النشر

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

انظر أيضًا

• AST — نظرة عامة على القدرة
• الإسقاط — مرجع متعمّق
• مسار الإخراج — مرجع متعمّق