البدء السريع لأداة NextPDF Backport Builder

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

لمحة سريعة

ستشغّل ثلاثة أوامر. أولًا، شغّل التجربة الجافة للتأكد من أن خط الأنابيب موصول من دون المساس بالملفات. بعد ذلك، شغّل بناءً كاملًا على ⁨PHP 8.1.⁩ ثم شغّل بناءً كاملًا على ⁨PHP 7.4.⁩ تستخدم كل خطوة أمرًا واحدًا، مدعومًا بسكربت ⁨Composer⁩ أو باستدعاء موثَّق لـ scripts/build.php.

المتطلبات المسبقة

• مضيف بناء على ⁨PHP⁩ >=8.4 <9.0، مع تثبيت اعتماديات البناء (composer install، دون --no-dev). راجع /⁨integrations/backport/install/.⁩
• استنسخ مستودعات المصدر كأدلة شقيقة ضمن جذر مصدر واحد. يقرأ بناء ⁨PHP 8.1⁩ المستودعات nextpdf، وnextpdf-Artisan، وnextpdf-compat-legacy، وnextpdf-Laravel، وnextpdf-Symfony، وnextpdf-CodeIgniter، وnextpdf-Pro (لإصدار ⁨Pro⁩). ويقرأ بناء ⁨PHP 7.4⁩ المستودع nextpdf فقط. مُتحقَّق منه مقابل scripts/merge-sources.php.

الخطوة 1 — التجربة الجافة

تُشغّل التجربة الجافة كل مرحلة في وضع الإبلاغ فقط. تسرد مرحلة الدمج الملفات التي ستنسخها. يُعلن الأمر عن ⁨Rector⁩ لكنه لا يُشغّله. تطبع مراحل توليد ⁨composer⁩ ونسخ الأصول والتحقق ما تنوي فعله. لا يُكتب أي شيء. شغّل هذا أولًا لأنه أسرع طريقة للتأكد من تخطيط المصدر والرايات.

composer build:dry

يُترجَم composer build:dry إلى php scripts/build.php --dry-run. مُتحقَّق منه مقابل composer.jsonscripts وscripts/build.php (فرع dryRun في كل مرحلة). مع الرايات الافتراضية، يكون الهدف php81، ويستخدم جذر المصدر الافتراضي الخاص بالسكربت. يمكنك تجاوز أي من القيمتين كما هو موضّح في الخطوة 2.

إذا أبلغت التجربة الجافة عن مستودع مصدر مفقود، فستتوقف فورًا وتذكر اسم ذلك المستودع. أصلح تخطيط المصدر قبل المتابعة. راجع /⁨integrations/backport/troubleshooting/.⁩

الخطوة 2 — بناء كامل على ⁨PHP 8.1⁩

يُشغّل بناء ⁨PHP 8.1⁩ عدة خطوات بالترتيب. يدمج النواة مع محوّلات أطر العمل وطبقة التوافق مع ⁨tcpdf.⁩ ويُشغّل تهيئة ⁨Rector⁩ ذات التمريرة الواحدة. يولّد nextpdf/backportcomposer.json. وينسخ الترخيص، ويكتب CHANGELOG.md، ويعدّ ملفات ⁨PHP⁩ المُصدَرة.

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

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

عند النجاح، يطبع المنسّق الوقت المنقضي ومسار الناتج. وعند تضمين ⁨Pro⁩، يطبع أيضًا مسار ناتج ⁨Pro.⁩ يحتوي دليل الناتج حينها على src/، وtests/، وcomposer.json مولّد يُعلن خريطة replace ومتطلبات الحشوات (⁨polyfill⁩)، وLICENSE، وCHANGELOG.md.

الخطوة 3 — بناء كامل على ⁨PHP 7.4⁩

بناء ⁨PHP 7.4⁩ مقتصر على النواة ويستخدم خط الأنابيب ذا التمريرتين. يُشغّل المعالجة المسبقة للتعدادات (⁨enum⁩)، ويمسح ذاكرة التخزين المؤقت، ويطبّق التصحيحات اللاحقة لـ ⁨Rector⁩، ثم ينفّذ خفض الإصدار بالكامل.

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

مُتحقَّق منه مقابل scripts/build.php. هنا، تفرض --target=php74 الاقتصار على النواة، وتعطّل ⁨Pro⁩، وتجعل runRector() تختار مسار التمريرتين. يحمل composer.json المولّد القيد >=7.4 <8.1. يستبدل nextpdf/core فقط، ويضيف حشوات ⁨PHP 8.0⁩ و8.1 فوق حشوات 8.2–8.5.

الخطوة 4 — قراءة الناتج

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

للتحقق الكامل، شغّل فحص بناء الجملة تحت إصدار ⁨PHP⁩ الهدف. يتّبع سير عمل الإصدار المسار نفسه. يفحص بناء جملة الناتج على ⁨PHP 8.1⁩ (أو ⁨PHP 7.4⁩)، ثم يثبّته ويختبره عبر مصفوفة الدعم. راجع /⁨integrations/backport/production-usage/.⁩

ما الذي بنيته

المُصنَع	بُني بواسطة	القيد	يستبدل
nextpdf/backport (⁨PHP 8.1⁩)	الخطوة 2	>=8.1 <8.5	⁨core⁩ + ⁨artisan⁩ + ⁨laravel⁩ + ⁨symfony⁩ + ⁨codeigniter⁩ + ⁨compat-legacy⁩
nextpdf/backport-pro (⁨PHP 8.1⁩)	الخطوة 2، عند تضمين ⁨Pro⁩	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (⁨PHP 7.4⁩)	الخطوة 3	>=7.4 <8.1	nextpdf/core

مُتحقَّق منه مقابل scripts/adjust-composer.php.

التالي

• /⁨integrations/backport/production-usage/⁩ — صِل هذا بسير عمل الإصدار المدفوع بالأحداث.
• /⁨integrations/backport/configuration/⁩ — مرجع القواعد والرايات التي تستند إليها هذه الأوامر.
• /⁨integrations/backport/troubleshooting/⁩ — معنى كل فشل في المراحل.