مرجع API الخاص بـ Backport Builder

لمحة سريعة

أداة ⁨Backport Builder⁩ أداة بناء، وليست مكتبة تُستخدم في وقت التشغيل. تتكوّن واجهتها العامة من مجموعة أوامر البناء (scripts/build.php وأغلفة composer build* الخاصة به)، والأصناف الأربعة على مستوى السكربت التي تقف خلفها (Build، MergeSources، AdjustComposer، ValidateBuildContract)، وملفات إعدادات ⁨Rector⁩ الثلاثة، وقواعد ⁨Rector⁩ المخصصة الثلاث، وعقد الحزمة المولَّدة (nextpdf/backport وnextpdf/backport-pro). شغِّلها على مضيف بناء أو في تكامل مستمر (⁨CI⁩) لتحويل مصدر ⁨NextPDF⁩ الحديث إلى توزيعة مخفَّضة. لا تُضِفها إلى أي تطبيق أبدًا.

إن كنت مستخدمًا جديدًا، فابدأ بـ composer build:dry (الذي يُترجَم إلى php scripts/build.php --dry-run). ينفِّذ هذا الأمر كل مرحلة في وضع التقرير فقط من دون كتابة ملفات، لتتمكن من التحقق من تخطيط المصدر والرايات قبل البناء الفعلي. يعرض أول مثال في “المهام الشائعة” الأمر نفسه.

المهام الشائعة

غالبًا ستستخدم هذه الحزمة لتشغيل عمليات البناء على مضيف بناء. كل مثال أدناه أمر واحد جرى التحقق منه مقابل scripts/build.php وcomposer.json.

تحقَّق من سلامة خط الأنابيب من دون كتابة أي شيء (التشغيل الأول الآمن):

composer build:dry

يُترجَم إلى php scripts/build.php --dry-run. يشغِّل الدمج و⁨Rector⁩ وتوليد ⁨composer⁩ ونسخ الأصول والتحقق في وضع التقرير فقط، من دون نسخ أي شيء.

أنتِج توزيعة ⁨PHP 8.1⁩ الكاملة (nextpdf/backport، إضافةً إلى nextpdf/backport-pro عند وجود مصدر ⁨Pro⁩):

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

يدمج هذا الأمر النواة ومحوِّلات أطر العمل وطبقة التوافق مع ⁨tcpdf.⁩ يشغِّل مرور ⁨Rector⁩ الواحد لهدف ⁨PHP 8.1⁩ ويكتب شجرة الحزمة المولَّدة إلى ./output. أضِف --no-pro لتخطّي حزمة ⁨Pro.⁩

أنتِج توزيعة ⁨PHP 7.4⁩ المقتصرة على النواة (خط أنابيب التعدادات ذو المرورَين):

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

يفرض --target=php74 إخراجًا مقتصرًا على النواة، ويعطِّل ⁨Pro⁩، ويشغِّل المعالجة المسبقة للتعدادات، والإصلاحات اللاحقة لـ ⁨Rector⁩، ومرور الخفض الكامل إلى ⁨PHP 7.4.⁩

واجهات الأوامر

استخدم هذا الجدول عندما تحتاج إلى التواقيع الدقيقة والرايات وسلوك الخروج لنقاط دخول البناء والأصناف على مستوى السكربت التي تدير عملية البناء.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يطرح استثناءً أو يفشل بـ	ملاحظات
scripts/build.php	الهدف والإصدار ومسارات المصدر ومسارات الإخراج والرايات كما هو موثَّق في السكربت.	يستخدم القيم الافتراضية للهدف الخاصة بالفرع.	شجرة الحزمة المولَّدة.	خروج بقيمة غير صفرية ومخرجات خطأ خاصة بالمرحلة.	نقطة الدخول الرئيسة للبناء. شغِّلها على مضيف بناء، لا داخل تطبيق.
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)	الإصدار، ودليل المصدر، ودليل الإخراج، ومسار وقت التشغيل الهدف، وراية تضمين ⁨Pro⁩، وراية التشغيل التجريبي.	يستهدف ⁨PHP 8.1⁩، ويضمِّن ⁨Pro⁩ باستثناء ⁨PHP 7.4⁩، ويكتب ما لم يُفعَّل التشغيل التجريبي.	Build	InvalidArgumentException للهدف غير المدعوم؛ وأخطاء المراحل أثناء run().	صنف على مستوى السكربت خلف scripts/build.php.
Build::run()	لا شيء.	يتحقق من العقد، ويدمج المصادر، ويعدِّل بيانات composer.json الوصفية، ويشغِّل مرورات ⁨Rector.⁩	bool	القيمة المُعادة false في حالات فشل المراحل المتوقَّعة؛ وقد يطرح استثناءً للأخطاء غير المتوقَّعة في نظام الملفات أو وقت التشغيل.	ينبغي أن يفشل ⁨CI⁩ عند false.
composer build:dry	غلاف سكربت ⁨Composer.⁩	التحقق من البناء بتشغيل تجريبي.	حالة الخروج والسجلات.	خروج بقيمة غير صفرية عند فشل البناء أو التحقق.	استخدمها في بوابات ⁨CI.⁩
scripts/merge-sources.php	مسارات سحب المصدر وهدف الدمج.	يدمج حزم المصدر المحددة لوقت التشغيل الهدف.	شجرة المصدر المدموجة.	مصدر مفقود، أو هدف غير مدعوم، أو فشل في نظام الملفات.	أبقِ مراجع المصدر متوافقة مع وسم الإصدار.
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)	دليل المصدر الأساسي، ودليل الإخراج، وراية تضمين ⁨Pro⁩، وراية التشغيل التجريبي، وراية الاقتصار على النواة.	يدمج جميع المستودعات المُهيَّأة، أو النواة فقط عندما تكون coreOnly صحيحة.	MergeSources	مسارات مصدر أو إخراج غير صالحة أثناء التشغيل.	صنف على مستوى السكربت خلف scripts/merge-sources.php.
MergeSources::run()	لا شيء.	ينسخ أشجار المصدر المحددة ويُطبِّعها داخل هدف البناء.	bool	القيمة المُعادة false في حالات فشل الدمج المتوقَّعة.	اقرأ السجلات باستخدام getLog().
MergeSources::getLog()	لا شيء.	يُعيد مدخلات سجل المراحل المتراكمة.	array	لا شيء متوقَّع.	استخدمها لتشخيص الـ ⁨CI.⁩
scripts/adjust-composer.php	بيانات composer.json الوصفية المولَّدة وإصداره.	يكتب قيود الحزم ومدخلات ⁨replace⁩ للمخرجات المولَّدة.	ملف composer.json.	إصدار غير صالح أو ملفات مولَّدة مفقودة.	يحدِّد هوية الحزمة المولَّدة.
AdjustComposer::__construct(string $version, string $target = 'php81')	سلسلة الإصدار والمسار الهدف.	هدف ⁨PHP 8.1.⁩	AdjustComposer	أخطاء هدف غير صالح في مسارات التوليد.	تستخدمها سكربتات البناء والاختبارات.
AdjustComposer::generatePublicComposer()	لا شيء.	يُنتج البيانات الوصفية لـ nextpdf/backport.	array	لا شيء متوقَّع.	واجهة توليد خالصة للاختبارات.
AdjustComposer::generateProComposer()	لا شيء.	يُنتج البيانات الوصفية لـ nextpdf/backport-pro.	array	لا شيء متوقَّع.	واجهة توليد خالصة لمسار البناء الاحتكاري.
AdjustComposer::writePublicComposer(string $outputDir)	دليل الإخراج.	يكتب الملف العام المولَّد composer.json.	void	أخطاء في نظام الملفات.	استخدمها فقط في أدلة الإخراج المولَّدة.
AdjustComposer::writeProComposer(string $proOutputDir)	دليل إخراج ⁨Pro.⁩	يكتب ملف ⁨Pro⁩ المولَّد composer.json.	void	أخطاء في نظام الملفات.	يتطلب وجود شجرة إخراج ⁨Pro.⁩
ValidateBuildContract::__construct(string $repoRoot)	جذر المستودع.	يستخدم جذر المستودع المُقدَّم أساسًا للعقد.	ValidateBuildContract	لا شيء متوقَّع.	مدقِّق للعقد على مستوى السكربت.
ValidateBuildContract::run()	لا شيء.	يفحص المدخلات المطلوبة وافتراضات البناء.	bool	القيمة المُعادة false عند فشل العقد.	شغِّلها قبل الوثوق بمخرجات البناء.

إعدادات ⁨Rector⁩

استخدم هذا الجدول لمعرفة ملف إعدادات ⁨Rector⁩ الذي يدير كل مسار هدف، وموضع كل مرور في خط أنابيب ⁨PHP 8.1⁩ ذي المرور الواحد أو ⁨PHP 7.4⁩ ذي المرورَين.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يطرح استثناءً أو يفشل بـ	ملاحظات
rector/config/rector-php81.php	شجرة المصدر ووقت تشغيل ⁨Rector.⁩	خفض بمرور واحد إلى هدف ⁨PHP 8.1.⁩	المصدر المحوَّل.	فشل تحليل أو تحويل في ⁨Rector.⁩	يُستخدم لمسار توزيعة ⁨PHP 8.1.⁩
rector/config/rector-php74-enums.php	شجرة المصدر ووقت تشغيل ⁨Rector.⁩	أول مرور ⁨PHP 7.4⁩ لتحويل التعدادات.	مصدر محوَّل وسيط.	فشل تحليل أو تحويل في ⁨Rector.⁩	يُشغَّل قبل مرور ⁨PHP 7.4⁩ الكامل.
rector/config/rector-php74.php	مصدر وسيط ووقت تشغيل ⁨Rector.⁩	مرور الخفض الكامل إلى ⁨PHP 7.4.⁩	مصدر متوافق مع ⁨PHP 7.4.⁩	فشل تحليل أو تحويل في ⁨Rector.⁩	يُستخدم لمسار توزيعة ⁨PHP 7.4.⁩

القواعد المخصصة

استخدم هذا الجدول عند صيانة قواعد ⁨Rector⁩ الثلاث الخاصة بالمشروع أو توسيعها، وعندما تحتاج إلى عقد التابع لكل قاعدة والبنية النحوية التي تُحوِّلها.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يطرح استثناءً أو يفشل بـ	ملاحظات
DowngradeAsymmetricVisibilityRector	الخصائص أو المعاملات المُرقَّاة التي تستخدم الإظهار غير المتماثل.	إظهار عادي متوافق مع أوقات التشغيل الأقدم.	يحافظ على إظهار القراءة حيثما أمكن.	فشل قاعدة ⁨Rector.⁩	قيود الضابط (⁨setter⁩) خاصة بوقت الترجمة فقط وتُزال من المخرجات المولَّدة.
DowngradeAsymmetricVisibilityRector::getRuleDefinition()	لا شيء.	يُعيد البيانات الوصفية لقاعدة ⁨Rector⁩ وأمثلتها.	RuleDefinition	لا شيء متوقَّع.	يُبقي توثيق القاعدة مرئيًا لأدوات ⁨Rector.⁩
DowngradeAsymmetricVisibilityRector::getNodeTypes()	لا شيء.	يحدد أنواع العقد التي تفحصها القاعدة.	array<class-string<Node>>	لا شيء متوقَّع.	ينبغي أن يبقى النطاق ضيقًا لضمان تحويلات حتمية.
DowngradeAsymmetricVisibilityRector::refactor(Node $node)	عقدة في الشجرة النحوية المجرَّدة (⁨AST⁩).	يحوِّل الإظهار غير المتماثل حيثما وُجد.	`Node	null`	فشل قاعدة ⁨Rector.⁩
DowngradeCloneWithRector	clone() مع تجاوزات للخصائص.	نسخ مع إسنادات خصائص صريحة.	يستخدم متغيرات مؤقتة مولَّدة.	فشل قاعدة ⁨Rector.⁩	يجب أن يُشغَّل بعد خفض الخصائص للقراءة فقط.
DowngradeCloneWithRector::getRuleDefinition()	لا شيء.	يُعيد البيانات الوصفية للقاعدة وأمثلتها.	RuleDefinition	لا شيء متوقَّع.	تستخدمها تشخيصات ⁨Rector.⁩
DowngradeCloneWithRector::getNodeTypes()	لا شيء.	يحدد عقد الإرجاع والتعبير.	array<class-string<Node>>	لا شيء متوقَّع.	يُبقي القاعدة مركَّزة على البنية النحوية لـ ⁨clone-with⁩.
DowngradeCloneWithRector::refactor(Node $node)	عقدة في الشجرة النحوية المجرَّدة (⁨AST⁩).	يعيد كتابة ⁨clone-with⁩ إلى نسخ مع إسنادات.	`array	null`	فشل قاعدة ⁨Rector.⁩
DowngradeTraitConstantsRector	ثوابت السمات (⁨traits⁩) والإشارات إليها.	خصائص ساكنة وإشارات إلى الخصائص.	يحافظ على الإظهار حيثما أمكن.	فشل قاعدة ⁨Rector.⁩	يُزيل final لأن الخصائص الأقدم لا يمكن أن تكون نهائية (⁨final⁩).
DowngradeTraitConstantsRector::getRuleDefinition()	لا شيء.	يُعيد البيانات الوصفية للقاعدة وأمثلتها.	RuleDefinition	لا شيء متوقَّع.	تستخدمها تشخيصات ⁨Rector.⁩
DowngradeTraitConstantsRector::getNodeTypes()	لا شيء.	يحدد عقد السمات وجلب ثوابت الأصناف.	array<class-string<Node>>	لا شيء متوقَّع.	يُبقي القاعدة محصورة في ثوابت السمات.
DowngradeTraitConstantsRector::refactor(Node $node)	عقدة في الشجرة النحوية المجرَّدة (⁨AST⁩).	يعيد كتابة ثوابت السمات والإشارات إليها إلى خصائص متوافقة.	`Node	null`	فشل قاعدة ⁨Rector.⁩

عقد الحزمة المولَّدة

استخدم هذا الجدول لمعرفة ما تُصدِره أداة البناء: أسماء الحزم التي تثبِّتها المشاريع التابعة، والحزمة التي تحمل توزيعة ⁨Pro.⁩

الحزمة المنتَجة	دور وقت التشغيل	ملاحظات
nextpdf/backport	توزيعة وقت تشغيل مفتوحة المصدر مولَّدة.	تستبدل حزم nextpdf/* المحددة لوقت التشغيل الهدف.
nextpdf/backport-pro	توزيعة ⁨Pro⁩ احتكارية مولَّدة عند وجود مصدر ⁨Pro.⁩	تُنشَر بمعزل عن الحزمة مفتوحة المصدر.

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

• تستهلك أداة البناء إصدارات المصدر وتُصدِر منتجات مولَّدة. لا تُرقِّع المخرجات المولَّدة باعتبارها مصدر الحقيقة.
• يجب أن تكون لكل قاعدة مخصصة اختبارات تجهيز (⁨fixtures⁩) قبل إدخالها في خط أنابيب البناء.
• يجب أن تتحقق مهام الإصدار من المخرجات المولَّدة على وقت التشغيل الهدف، لا على مضيف البناء فقط.