استكشاف أخطاء أداة بناء النقل الخلفي في NextPDF وإصلاحها

هذه أدوات بناء، وليست اعتماديات وقت تشغيل. كل عَرَض في هذه الصفحة حالة وقت بناء على مضيف خاص بمشرف أو بالتكامل المستمر (⁨CI⁩). لا تظهر أيٌّ من هذه الحالات في تطبيق متفرّع لاحق.

لمحة سريعة

يُشغّل البناء خمس مراحل مرتّبة. يتوقّف عند أول إخفاق ويطبع اسم المرحلة والرسالة. اقرأ اسم المرحلة، ثم ابحث عن السبب المطابق أدناه. المراحل هي دمج المصادر، وتشغيل خفض إصدار ⁨Rector⁩، وتوليد composer.json، ونسخ الأصول الثابتة، والتحقّق من المُخرَج. جرى التحقّق مقابل scripts/build.php (run() وstep()).

المرحلة: دمج المصادر

”⁨Source repo⁩ '' ⁨not found at⁩: ”

يتحقّق الدمج من كل مستودع مصدر متوقَّع قبل نسخ الملفات. إذا كان أحد المستودعات مفقودًا، يُجهَض البناء ويطبع اسمه ومساره. يتوقّع هدف ⁨PHP 8.1⁩ وجود nextpdf، وnextpdf-Artisan، وnextpdf-compat-legacy، وnextpdf-Laravel، وnextpdf-Symfony، وnextpdf-CodeIgniter، و — عند تضمين ⁨Pro⁩ — nextpdf-Pro. يتوقّع هدف ⁨PHP 7.4⁩ وجود nextpdf فقط. جرى التحقّق مقابل scripts/merge-sources.php (حلقة التحقّق في run()، وخريطة المستودعات في __construct()).

الحل: اسحب المستودعات بوصفها أدلّة شقيقة تحت المسار المُمرَّر إلى --source-dir، واستخدم أسماء الأدلّة الدقيقة الواردة أعلاه. يسرد التشغيل التجريبي كل مستودع سيقرؤه. استخدمه للتحقّق من البنية قبل تشغيل بناء كامل.

المرحلة: تشغيل خفض إصدار ⁨Rector⁩

يخرج ⁨Rector⁩ برمز غير صفري

يُبلّغ المنسّق عن Rector failed on <label> (exit code: N) ثم يتوقّف. تحدّد التسمية المرور الذي أخفق: public package، أو pro package، أو enum pre-processing، أو full downgrade. جرى التحقّق مقابل scripts/build.php (runRectorPass()).

انهيار مُحلِّل المعامِلات الافتراضية على قيم ⁨enum⁩ الافتراضية (⁨PHP 7.4⁩)

لهذا السبب يستخدم هدف ⁨PHP 7.4⁩ مرورين. ينهار مُحلِّل قيم المعامِلات الافتراضية في ⁨Rector⁩ عندما تُستخدَم حالة ⁨enum⁩ بوصفها قيمة افتراضية لترقية مُنشئ. يحوّل المرور الأول (rector-php74-enums.php) الـ ⁨enum⁩ إلى أصناف ذات قوائم ثوابت أولًا. عندها لا يرى المرور الكامل في المرور الثاني أبدًا قيمة افتراضية لحالة ⁨enum.⁩ إذا تجاوزت المنسّق وشغّلت تهيئة ⁨PHP 7.4⁩ الكاملة مباشرةً على مصدر يحتوي على ⁨enum⁩، فتوقّع هذا الانهيار. جرى التحقّق مقابل scripts/build.php (تعليق runRector() وتسلسل المرورين) وrector/config/rector-php74-enums.php.

سكربتات قياس الأداء تُنهي ⁨Rector⁩ بانهيار

يتخطّى rector-php81.php وrector-php74.php المسار */tests/Benchmark/*. تشير تلك السكربتات إلى مكتبات خارجية لتنسيق المستندات المحمول (⁨PDF⁩) لا يستطيع ⁨Rector⁩ تحليلها، ما يسبّب انهيار مُحلِّل المعامِلات الافتراضية. إذا عولج مسار قياس أداء، فهذا يعني أن نمط التخطّي مفقود أو أن المسار مختلف. جرى التحقّق مقابل استدعاءات withSkip().

انهيار MHASH_XXH* (⁨PHP 7.4⁩)

يتخطّى rector-php74.php القاعدة DowngradeHashAlgorithmXxHashRector. تنهار تلك القاعدة المُدمَجة عند التعامل مع ثوابت ⁨xxHash.⁩ لا يستخدم المصدر ⁨xxHash⁩، لذا فإن التخطّي آمن. جرى التحقّق مقابل rector/config/rector-php74.php (withSkip()).

المرحلة: تصحيحات ما بعد ⁨Rector⁩ (⁨PHP 7.4⁩ فقط)

تُشغَّل التصحيحات بين المرورين. تعيد هذه التصحيحات كتابة الأنماط التي خلّفتها قاعدة التحويل من ⁨enum⁩ إلى صنف. إذا كان مُخرَج ⁨PHP 7.4⁩ يحتوي على خطأ تحليل يتعلّق بـ EnumClass::Case->value، أو ->name، أو دالّة ⁨enum⁩ سابقة استُدعيت بوصفها دالّة نسخة، أو وسيطًا مُسمّى على نوع غير محلول، فهذا يعني أن التصحيح لم يطابق ذلك النمط. ينطبق قيد ⁨clone-with⁩ هنا أيضًا: مطابقة الوسائط ليست تعاودية، لذا فإن قيمة تجاوُز تحتوي على أقواس متداخلة لا يُعاد كتابتها. جرى التحقّق مقابل scripts/build.php (postProcessFixups()، وfixEnumMethodCallSites()، وapplyFixups()) وrector/rules/DowngradeCloneWithRector.php (قيد موثَّق).

المرحلة: توليد ⁨composer.json⁩

تنقل هذه المرحلة الدليلين المُعالَجين src/ وtests/ من دليل بناء مؤقّت إلى دليل المُخرَج. ثم تكتب ملف composer.json المُولَّد. يكون الإخفاق هنا دائمًا تقريبًا حالة في نظام الملفات: دليل المُخرَج غير قابل للكتابة، أو شجرة البناء المؤقّت مفقودة لأن ⁨Rector⁩ لم يُنتج شيئًا. جرى التحقّق مقابل scripts/build.php (adjustComposer()، وmoveTree()).

المرحلة: نسخ الأصول الثابتة

تنسخ هذه المرحلة LICENSE من مستودع المصدر الأساسي وتكتب ملف CHANGELOG.md مُولَّدًا. إذا كان LICENSE غائبًا، يُتخطّى النسخ بصمت ويستمرّ البناء؛ أما سجلّ التغييرات فيُكتَب دائمًا. يعني الإخفاق هنا أن دليل المُخرَج أصبح غير قابل للكتابة أثناء البناء. جرى التحقّق مقابل scripts/build.php (copyStaticAssets()).

المرحلة: التحقّق من المُخرَج

”⁨Output src/ directory not found⁩” / “⁨No PHP files found in output⁩”

يتطلّب التحقّق أن يكون output/src غير فارغ. تعني الشجرة الفارغة أن الدمج لم ينسخ شيئًا، أو أن نقل الملفات أخفق. جرى التحقّق مقابل scripts/build.php (validateOutput()).

”⁨Syntax validation⁩: ⁨skipped⁩ (⁨requires PHP⁩ ⁨runtime⁩)”

هذا متوقَّع وليس خطأً. يُشغّل مضيف البناء إصدار ⁨PHP⁩ حديثًا، وليس وقت التشغيل الهدف، لذلك تكتفي المرحلة المحلية بعدّ الملفات وطباعة أمر ⁨Docker⁩ لإجراء فحص صياغة حقيقي. بوابة الصياغة المرجعية هي خطوة php -l اللاحقة للبناء في سير عمل الإصدار، وهي تعمل تحت وقت التشغيل الهدف الفعلي. جرى التحقّق مقابل scripts/build.php (validateOutput()) و.github/workflows/build.yml (خطوتا فحص صياغة ⁨PHP 8.1⁩ / ⁨PHP 7.4⁩).

القيود المعروفة

هذه القيود متأصّلة في نهج خفض الإصدار. جرى التحقّق منها مقابل القواعد وقسم “⁨Known Limitations⁩” في README.md الخاص بالمشروع:

• تُزال خصائص ⁨readonly.⁩ يجرّد البناء readonly حتى يتمكّن توسيع ⁨clone-with⁩ من إسناد الخصائص صراحةً في وقت التشغيل الأقدم. لم يعد المُخرَج المخفَّض الإصدار يتمتّع بثبات مفروض في وقت التشغيل.
• #[Override] غير مفروض على ⁨PHP 8.1.⁩ قد تبقى السمة، لكن وقت التشغيل الأقدم لا يتصرّف وفقًا لها.
• هدف ⁨PHP 7.4⁩ أساسي فقط. تُستبعَد محوّلات أُطر العمل، وطبقة التوافق مع ⁨tcpdf⁩، و⁨Pro⁩ من توزيعة ⁨PHP 7.4⁩ بحكم بنية سكربت البناء.
• ⁨Pro⁩ حزمة منفصلة وبإصدار ⁨PHP 8.1⁩ فقط. لا يوجد بناء ⁨Pro⁩ بإصدار ⁨PHP 7.4.⁩
• مطابقة وسائط ⁨clone-with⁩ ليست تعاودية. قيم التجاوُز التي تحتوي على أقواس متداخلة لا تُحوَّل، ولا تُحَلّ إلى أسماء خصائص إلا مفاتيح المصفوفات النصّية.

التالي

• /⁨integrations/backport/configuration/⁩ — مرجع القواعد والأعلام.
• /⁨integrations/backport/production-usage/⁩ — بوابة ⁨CI⁩ ومسارات الإصدار.