تهيئة NextPDF Backport Builder

أدوات بناء، وليست تبعية وقت تشغيل. كل ما في هذه الصفحة يهيّئ تحويل المصدر في وقت البناء. لا يُشحَن أي منها إلى وقت تشغيل لاحق.

نظرة سريعة

تقود التحويلَ ثلاثة ملفات إعداد لـ ⁨Rector⁩ ضمن rector/config/ وثلاث قواعد مخصّصة ضمن rector/rules/. يعتمد الإعداد المحدَّد على الهدف. يستخدم هدف ⁨PHP 8.1⁩ مرورًا واحدًا لـ ⁨Rector.⁩ أما هدف ⁨PHP 7.4⁩ فيستخدم مسارًا ثنائي المرور مع مرحلة إصلاح بين المرورين. المرور الثاني مطلوب لأن ⁨Rector⁩ لا يستطيع حلّ القيم الافتراضية لحالات التعداد في اجتياز واحد.

إعدادات ⁨Rector⁩

الملف	الغرض	يستخدمه
rector/config/rector-php81.php	خفض أحادي المرور إلى ⁨PHP 8.1⁩	هدف ⁨PHP 8.1⁩
rector/config/rector-php74-enums.php	المرور 1 — تحويل التعدادات إلى أصناف بقوائم ثوابت	هدف ⁨PHP 7.4⁩
rector/config/rector-php74.php	المرور 2 — خفض كامل إلى ⁨PHP 7.4⁩	هدف ⁨PHP 7.4⁩

يستدعي كل إعداد سلسلة مجموعات الخفض الخاصة بـ ⁨Rector⁩ (withDowngradeSets(php81: true) أو withDowngradeSets(php74: true)) للميزات التي يعالجها ⁨Rector⁩ أصلًا. ثم يسجّل قواعد مخصّصة للميزات المتبقية. جرى التحقق من ذلك مقابل الملفات الثلاثة في rector/config/.

قواعد التخطّي

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

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

يشحن المستودع ثلاث قواعد ⁨Rector⁩ مخصّصة بالضبط. القواعد الثلاث كلها مسجَّلة في rector-php81.php؛ كما تُسجَّل قواعد الرؤية اللامتماثلة و⁨clone-with⁩ وثوابت السمات أيضًا في rector-php74.php. يؤكّد tests/Rector/RectorRulesMetadataTest.php ذلك مباشرة عبر إنشاء كل قاعدة والتحقق من تعريفها وأنواع عُقدها.

DowngradeAsymmetricVisibilityRector

يزيل معدِّل المجموعة ذي الرؤية اللامتماثلة. تُصبح الخاصية أو المعامل المُرقَّى المُعلَن public private(set) مجرد public. يُحفَظ وصول القراءة، ويُسقَط قيد الإسناد في وقت الترجمة. عندما لا تبقى أي رؤية للقراءة، تعود القاعدة افتراضيًا إلى public. هذا تحويل مدعوم بالمصدر من tests/Rector/Fixtures/DowngradeAsymmetricVisibility/public_private_set.php.inc:

before

<?php

class Config {
    public private(set) float $x = 0.0;
    public private(set) string $name = '';
    public private(set) int $count = 0;
}

after

<?php

class Config {
    public float $x = 0.0;
    public string $name = '';
    public int $count = 0;
}

DowngradeCloneWithRector

يعيد كتابة الشكل الدالّي clone() المصحوب بمصفوفة تجاوزات إلى عملية استنساخ وإسنادات خصائص صريحة وإرجاع متغيّر مؤقّت. يُعاد ضبط عدّاد المتغيّر المؤقّت لكل ملف. يجب تشغيل هذه القاعدة بعد قاعدة إزالة خصائص القراءة فقط؛ وإلا فسيفشل الإسناد الموسَّع عند التعامل مع خاصية للقراءة فقط. هذا تحويل مدعوم بالمصدر من tests/Rector/Fixtures/DowngradeCloneWith/return_clone_with.php.inc:

before

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self {
        return clone($this, ['width' => $width, 'height' => $height]);
    }
}

after

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self
    {
        $__cloneResult1 = clone $this;
        $__cloneResult1->width = $width;
        $__cloneResult1->height = $height;
        return $__cloneResult1;
    }
}

للقاعدة قيود موثَّقة. تستخدم مطابقة الوسائط نمطًا غير تعاودي، لذلك لا تُعالَج قيم التجاوز ذات الأقواس المتداخلة. ولا تُحَلّ إلى أسماء خصائص إلا مفاتيح المصفوفة النصية. جرى التحقق من ذلك مقابل rector/rules/DowngradeCloneWithRector.php ومجموعة تركيباته الاختبارية.

DowngradeTraitConstantsRector

يحوّل ثوابت السمات إلى خصائص ساكنة. ترفض أوقات التشغيل الأقدم ثوابت السمات بالرسالة “⁨Traits cannot have constants⁩”. تعيد القاعدة أيضًا كتابة مراجع self::CONST وstatic::CONST إلى شكل الخاصية الساكنة. تُحفَظ الرؤية، ويُجرَّد معدِّل final لأن الخصائص لا يمكن أن تكون ⁨final⁩ على الهدف الأقدم. ويُحوَّل ثابت الصنف المُنمَّط إلى خاصية مُنمَّطة. هذا تحويل مدعوم بالمصدر من tests/Rector/Fixtures/DowngradeTraitConstants/private_constant.php.inc:

before

<?php

trait HasLimit
{
    private const MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::MAX_SIZE;
    }
}

after

<?php

trait HasLimit
{
    private static $MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::$MAX_SIZE;
    }
}

مسار ⁨PHP 7.4⁩ ثنائي المرور

لا يمكن لهدف ⁨PHP 7.4⁩ أن يعمل في مرور واحد. يتعطّل محلّل القيم الافتراضية للمعاملات الخاص بـ ⁨Rector⁩ عند القيم الافتراضية لحالات التعداد في ترقية الباني. لذلك ينفّذ سكربت البناء ما يلي:

1. المرور 1 — المعالجة المسبقة للتعدادات. يشغّل rector-php74-enums.php قاعدة تحويل التعداد إلى صنف بقائمة ثوابت المضمَّنة فقط. بعد هذا المرور، تُصبح حالات التعداد ثوابت صنف عادية.
2. مسح ذاكرة التخزين المؤقّت. تُمسَح ذاكرة ⁨Rector⁩ المؤقّتة كي لا يرى المرور الثاني شجرة قديمة.
3. إصلاحات ما بعد المعالجة. يعيد scripts/build.php كتابة الأنماط التي لا تغطّيها قاعدة تحويل التعداد إلى صنف. تُصبح أساليب نسخ التعداد السابقة ساكنة. وتُحَلّ عمليات الوصول EnumClass::Case->value و->name. وتُسطَّح الوسائط المسمّاة التي تعذّر على ⁨Rector⁩ ربطها إلى وسائط موضعية. كانت هذه الأنماط النحوية ستسبّب أخطاء تحليل على ⁨PHP 7.4⁩ لولا ذلك.
4. المرور 2 — الخفض الكامل. يشغّل rector-php74.php سلسلة خفض ⁨PHP 7.4⁩ الكاملة إضافة إلى القواعد المخصّصة.

جرى التحقق من ذلك مقابل scripts/build.php (runRector()، postProcessFixups()).

مرجع أعلام البناء

ينسّق scripts/build.php البناء. جرى التحقق من خياراته مقابل استدعاء getopt() وباني Build:

العَلَم	الافتراضي	الأثر
--version=<x.y.z>	2.0.0	الإصدار المكتوب في composer.json وCHANGELOG.md المولَّدين
--source-dir=<path>	c:/Users/admin/Documents	الجذر الحاوي على مستودعات المصدر الشقيقة
--output-dir=<path>	<repo>/output	حيث تُكتَب التوزيعة المولَّدة
--target=php74 | --target=php81	php81	هدف الخفض. php74 يفرض النواة فقط ويُعطّل ⁨Pro⁩
--dry-run	مُعطَّل	تشغيل كل مرحلة في وضع التقرير فقط؛ يُتخطّى النسخ و⁨Rector⁩
--no-pro	مُعطَّل	استبعاد حزمة ⁨Pro⁩ (هدف ⁨PHP 8.1⁩ فقط؛ ⁨PHP 7.4⁩ يستبعدها بالفعل)

تثير قيمة --target غير الصالحة استثناء InvalidArgumentException قبل بدء أي عمل. جرى التحقق من ذلك مقابل Build::__construct() (حارس VALID_TARGETS).

سكربتات ⁨Composer⁩

السكربت	الأمر	الغرض
composer test	phpunit	تشغيل مجموعات تركيبات اختبار القواعد
composer analyse	phpstan analyse rector/rules scripts --level=10	التحليل الساكن لشيفرة البناء
composer build	php scripts/build.php	بناء كامل
composer build:dry	php scripts/build.php --dry-run	بناء بوضع التجربة

جرى التحقق من ذلك مقابل composer.jsonscripts.

التالي

• /⁨integrations/backport/quickstart/⁩ — تشغيل وضع التجربة والبناء الكامل.
• /⁨integrations/backport/troubleshooting/⁩ — معنى كل مرحلة فشل.