نظرة عامة إلى أداة بناء التوافق العكسي في NextPDF

هذه أداة بناء، وليست اعتمادية وقت تشغيل. يستخدم مشرفو صيانة ⁨NextPDF⁩ هذه الحزمة لإنتاج توزيعات من ⁨NextPDF⁩ متوافقة مع ⁨PHP 8.1⁩ وما بعده و⁨PHP 7.4⁩ وما بعده. يجب ألا تضيفها التطبيقات أبدًا بوصفها اعتمادية وقت تشغيل.

لمحة سريعة

أداة بناء التوافق العكسي في ⁨NextPDF⁩ هي بنية تحتية للبناء تنتج توزيعة من منظومة ⁨NextPDF⁩ بعد خفض مستوى توافقها، لتعمل في بيئات تشغيل ⁨PHP⁩ الأقدم من خط الأساس التطويري. كُتب ⁨NextPDF⁩ لإصدار حديث من ⁨PHP⁩، ويستخدم تراكيب لغوية ترفضها المفسِّرات الأقدم. تُمرِّر الأداة المصدر عبر ⁨Rector⁩، وهو محرك يحوِّل أشجار البنية اللغوية المجردة، وتُصدر حزمًا تقبل بيئة تشغيل ⁨PHP 8.1⁩ أو ⁨PHP 7.4⁩ بنيتها اللغوية.

اسم حزمة ⁨Composer⁩ هو nextpdf/backport-builder. تُعلن "type": "project" ولا تحمل أي اعتمادية وقت تشغيل لـ ⁨NextPDF⁩. تقتصر متطلباتها على محرك البناء (rector/rector)، والتحليل الساكن (phpstan/phpstan)، ومُشغِّل الاختبارات (phpunit/phpunit)، ومجموعة من حزم symfony/polyfill-* المستخدمة في المُخرَج المُولَّد. يؤكد ذلك ملف composer.json الموجود في جذر المستودع.

ما لا تمثله هذه الحزمة

لا يحتوي هذا المستودع على محرك ⁨NextPDF⁩. بل يحتوي على القواعد والنصوص البرمجية التي تحوِّل ذلك المحرك إلى صيغة متوافقة عكسيًا. ويترتب على هذا الفصل ثلاثة آثار عملية:

• لا تُثبِّت هذه الحزمة لعرض ملفات ⁨PDF⁩. ثبِّت nextpdf/backport، فهو المُخرَج الذي تنتجه هذه الأداة. أبقِ الأداة على مضيف الصيانة أو مضيف التكامل المستمر (⁨CI⁩).
• لا تبنِ تطويرك على الشيفرة المُولَّدة. التوزيعة المُولَّدة مُخرَج للقراءة فقط أنتجته الآلة. أرسِل بلاغات الأخطاء وطلبات الميزات إلى مستودعات المصدر الأصلية nextpdf/*.
• يُشحَن المُخرَج على هيئة وسوم إصدار، لا على هيئة فروع لهذا المستودع. يضع خط أنابيب الإصدار وسمًا على الشجرة المُولَّدة، ويرفق الأرشيفات بإصدار على ⁨GitHub⁩.

ما الذي تنتجه

تُصدر الأداة حزم ⁨Composer⁩ التي يحدِّد الملف scripts/adjust-composer.php أسماءها وتراخيصها:

الحزمة المُنتَجة	الترخيص	النطاق	متى يُبنى
nextpdf/backport	Apache-2.0	النواة، ومحوِّلات أطر العمل، وطبقة التوافق مع ⁨tcpdf⁩ لهدف ⁨PHP 8.1⁩	دائمًا
nextpdf/backport-pro	proprietary	وحدة ⁨Pro⁩، وتُصدَر بوصفها حزمة منفصلة	هدف ⁨PHP 8.1⁩، عندما يكون مصدر ⁨Pro⁩ موجودًا ولا تُستبعَد ⁨Pro⁩

تُعلن حزمة nextpdf/backport إدخالات replace في ⁨Composer⁩ بحيث تستوفي، بعد التثبيت، قيود الحزم الأصلية. في هدف ⁨PHP 8.1⁩، تكون الحزم المُستبدَلة هي nextpdf/core، وnextpdf/artisan، وnextpdf/laravel، وnextpdf/symfony، وnextpdf/codeigniter، وnextpdf/compat-legacy. أما في هدف ⁨PHP 7.4⁩، فتُستبدَل nextpdf/core وحدها لأن بناء ⁨PHP 7.4⁩ يقتصر على النواة. يؤكد ذلك scripts/adjust-composer.php (buildReplace()).

يحلِّل المُحمِّل التلقائي لدى المستهلك الشجرة المدمَجة عبر بادئة واحدة من توصية معايير ⁨PHP⁩ رقم 4 (⁨PSR-4⁩)، وهي NextPDF\، المُسنَدة إلى src/. يُسنِد ⁨PSR-4⁩ بادئة مساحة الأسماء إلى دليل أساس، ويحلِّل كل اسم صنف مؤهَّل بالكامل إلى ملف تحته؛ راجع ⁨PSR-4⁩ الصادرة عن مجموعة التشغيل البيني لأطر عمل ⁨PHP⁩ (⁨PHP-FIG⁩). تُسنِد حزمة ⁨Pro⁩ NextPDF\Pro\ إلى src/ الخاص بها.

مصفوفة إصدارات ⁨PHP⁩ المدعومة

لا تعرض المصفوفة أدناه إلا ما تفرضه إعدادات ⁨Rector⁩ ونصوص البناء البرمجية. يعمل مضيف البناء دائمًا بإصدار حديث من ⁨PHP⁩. أما المُخرَج فيستهدف إصدارًا أقدم.

الجانب	القيمة	الدليل
إصدار ⁨PHP⁩ في مضيف البناء	>=8.4 <9.0	composer.jsonrequire.php
إصدار ⁨PHP⁩ لعمليات ⁨build/test⁩ في ⁨CI⁩	8.5	.github/workflows/0-ci.yml، build.yml (shivammathur/setup-phpphp-version: '8.5')
قيد مُخرَج الهدف ⁨PHP 8.1⁩	>=8.1 <8.5	scripts/adjust-composer.php (generatePublicComposer())
قيد مُخرَج الهدف ⁨PHP 7.4⁩	>=7.4 <8.1	scripts/adjust-composer.php (generatePublicComposer())
نطاق الهدف ⁨PHP 8.1⁩	النواة + ⁨Artisan⁩ + ⁨Laravel⁩ + ⁨Symfony⁩ + ⁨CodeIgniter⁩ + ⁨compat-legacy⁩ (+ ⁨Pro⁩، منفصلة)	scripts/merge-sources.php، scripts/adjust-composer.php
نطاق الهدف ⁨PHP 7.4⁩	النواة فقط	scripts/build.php (--target=php74 يفرض الاقتصار على النواة، مع تعطيل ⁨Pro⁩)

يُتحقَّق من بناء ⁨PHP 8.1⁩ على ⁨PHP 8.1⁩ و8.2 و8.3 و8.4. ويُتحقَّق من بناء ⁨PHP 7.4⁩ على ⁨PHP 7.4⁩ و8.0. تؤكد ذلك مصفوفتا المهام validate-php81 وvalidate-php74 في .github/workflows/build.yml. هذه هي بيئات التشغيل التي يختبرها خط الأنابيب. وهي مجموعة تحقُّق مرصودة بالاختبار، لا ادعاء عام بالمطابقة.

نموذج الفرعين

لا يوجد في هذا المستودع فرع main. PHP74 هو الفرع الافتراضي، وPHP81 هو الفرع الدائم الثاني. يحدِّد الفرع الذي تعمل عليه أمرين: الهدف الافتراضي للبناء المحلي، ومجموعة المصدر التي تُدمَج. طبِّق أي تغيير يؤثر في كلا الهدفين على كل فرع عبر طلب سحب خاص به. يعمل سير عمل ⁨CI⁩ على كلٍّ من PHP74 وPHP81. يمكن التحقق من ذلك بمقارنته مع git branch -a و.github/workflows/0-ci.yml (branches: [PHP74, PHP81]).

كيف يحدث الإصدار

مسار الإصدار مدفوع بالأحداث. عندما تنشر مؤسسة مصدر ⁨NextPDF⁩ وسم إصدار، يُطلِق حدث إيفاد للمستودع من النوع source-release سير عمل البناء. يسحب سير العمل كل مستودع مصدر عند الوسم المطابق، ويشغِّل خط الأنابيب، ويفحص توافق بنية المُخرَج اللغوية مع بيئة التشغيل المستهدفة، ويتحقق منه عبر مصفوفة الدعم، ويرفق الأرشيفات بإصدار على ⁨GitHub⁩. يتبع وسم الإصدار الإصدار الدلالي: رقم الإصدار هو MAJOR.MINOR.PATCH فوق واجهة برمجة تطبيقات عامة مُعلَنة (الإصدار الدلالي 2.0.0 §2). يؤكد ذلك .github/workflows/build.yml.

إلى أين تذهب بعد ذلك

• /⁨integrations/backport/install/⁩ — طريقة تثبيت الأداة على مضيف بناء، وطريقة تثبيت المستهلكين للحزمة المُنتَجة.
• /⁨integrations/backport/configuration/⁩ — إعدادات ⁨Rector⁩، والقواعد المخصصة، وأعلام البناء.
• /⁨integrations/backport/quickstart/⁩ — تشغيل تجريبي مدعوم بالمصدر واستدعاء بناء كامل.
• /⁨integrations/backport/production-usage/⁩ — طريقة ربط الأداة بسير عمل الإصدار.
• /⁨integrations/backport/troubleshooting/⁩ — أنماط الإخفاق التي يرصدها خط الأنابيب وكيفية قراءتها.
• /⁨integrations/backport/security-and-operations/⁩ — حالة سلسلة التوريد، وحدود الثقة، والضمانات التشغيلية.
• /⁨integrations/backport/boot-and-discovery/⁩ — كيف تكتشف الأداة وحدات المصدر وتُقلِع.
• /⁨integrations/backport/integration/⁩ — عقد التكامل مع مضيف البناء.