الترقية من PHP 8.2 إلى 8.4: قائمة تحقق عملية للشيفرة والامتدادات والخوادم

ينتهي عمر PHP 8.2 في 31 ديسمبر 2026، وPHP 8.4 هو المحطة التالية الطبيعية، إذ يحظى بدعم أمني حتى 31 ديسمبر 2028 وهو الإصدار الافتراضي في Debian 13. الانتقال من 8.2 إلى 8.4 يعبر مجموعتين من التغييرات، تغييرات 8.3 ثم تغييرات 8.4، لذا من المجدي العمل عليهما بالترتيب.

بُنيت قائمة التحقق هذه على دليلي الترحيل الرسميين، وأضفنا إليها خطوات الاختبار والخادم.

1. التحضير

• احصر لكل تطبيق: إصدار إطار العمل أو نظام إدارة المحتوى، وامتدادات PHP المستخدمة (php8.2 -m)، ومهام cron وعمّال الطوابير التي تشغّل PHP.
• تحقق من إطار العمل أولًا، ورقِّه إلى إصدار يدعم PHP 8.4 قبل لمس PHP نفسه.
• تحقق من قيود Composer، فهذا الأمر يعرض الحزم التي تمنع متطلباتها الانتقال إلى PHP 8.4:

  composer prohibits php 8.4

• جهّز نسخة تجريبية ببيانات مشابهة لبيئة الإنتاج، ولا تجرِ التشغيل الأول على الخادم الحي أبدًا.

2. التغييرات من 8.2 إلى 8.3

تغييرات غير متوافقة تستحق الفحص:

• أصبح امتداد Date يرمي في حالات كثيرة استثناءاته الخاصة من فئتي DateError وDateException بدل التحذيرات والاستثناءات العامة، فراجع كتل try/catch حول تحليل التواريخ.
• أصبحت range() أكثر صرامة: ترمي خطأً عند تمرير كائنات أو موارد أو مصفوفات حدودًا، وعند خطوة قيمتها 0، وعند خطوة سالبة لنطاق تصاعدي، وعند وسائط لا نهائية أو NAN.
• البرامج القريبة من تجاوز مكدس الاستدعاءات قد ترمي الآن Error، ويتحكم في ذلك الإعداد الجديد zend.max_allowed_stack_size.
• إسناد فهرس سالب $n إلى مصفوفة فارغة يجعل الفهرس التالي $n+1 بدل 0.
• أُزيل الإعداد opcache.consistency_checks.

الإهمالات التي أدخلها 8.3:

• استدعاء get_class() أو get_parent_class() دون وسائط.
• استخدام ++ على نصوص فارغة أو غير أبجدية رقمية (وبإهمال مرن على النصوص غير الرقمية)، والبديل str_increment().
• الدالة assert_options() والثوابت ASSERT_* وإعدادات assert.*.
• استدعاء ldap_connect() بمضيف ومنفذ منفصلين، وتمرير عرض سالب إلى mb_strimwidth()، واستدعاء ReflectionProperty::setValue() بوسيط واحد.

3. التغييرات من 8.3 إلى 8.4

تغييرات غير متوافقة تستحق الفحص:

• امتدادات أُخرجت من النواة: نُقلت IMAP وOCI8 وPDO_OCI وPSpell إلى PECL، فتحقق مما إذا كانت منصتك ما زالت توفر حزمًا لها (انظر الخطوة 5).
• أصبحت exit() وdie() تتصرفان أقرب إلى الدوال، فتخضعان لـ strict_types وللتحويل المعتاد بين الأنواع.
• أُزيل مستوى الخطأ E_STRICT وأصبح ثابته مُهملًا.
• تحولت عدة موارد إلى كائنات (DBA وODBC وأجزاء من SOAP)، فاستبدل فحوص is_resource() كما يشرح الدليل.
• كثير من الدوال أصبحت ترمي ValueError عند الوسائط غير الصالحة، ومنها round() بنمط غير صالح، وstr_getcsv() بفواصل متعددة البايتات، ودوال الصور في GD بقيمة جودة غير صالحة.
• أصبحت مكتبة PCRE2 المضمّنة بالإصدار 10.44، فصار {,3} مُكمِّمًا لا نصًا حرفيًا.
• تغيرت القيم الافتراضية لـ JIT إلى opcache.jit=disable مع opcache.jit_buffer_size=64M. ما زال JIT معطلًا افتراضيًا، لكن إن كنت فعّلته بضبط حجم المخزن فقط فتأكد أنه يعمل فعلًا.
• مع MySQL 8.0.24 وما بعده يبلّغ mysqlnd عن انتهاء مهلة انتظار الخادم بالرمز 4031 بدل 2006، فحدّث منطق إعادة الاتصال الذي يعتمد على الرمز 2006.

الإهمالات التي أدخلها 8.4، مرتبة تقريبًا بحسب تكرار ظهورها:

• المعاملات التي تقبل null ضمنيًا. يجب أن تصبح function f(Foo $x = null) بالشكل function f(?Foo $x = null)، وهذه عادةً أكبر دفعة من الرسائل.
• استدعاء trigger_error() مع E_USER_ERROR، والبديل رمي استثناء أو استدعاء exit().
• الاعتماد على القيمة الافتراضية للمعامل escape في fputcsv() وfgetcsv() وstr_getcsv()، فمرّره صراحةً.
• الدوال mysqli_ping() وmysqli_kill() وmysqli_refresh()، وlcg_value()، واستدعاء session_set_save_handler() بأكثر من وسيطين، وتغيير session.sid_length أو session.sid_bits_per_character.
• رفع الصفر إلى أس سالب، وتسمية صنف بالاسم _.

4. الاختبار

• افحص الصياغة بالإصدار 8.4. منذ PHP 8.3 يقبل php -l عدة ملفات دفعة واحدة، وهو يكشف أخطاء الصياغة لا مشكلات وقت التشغيل.

  find . -path ./vendor -prune -o -name '*.php' -print0 | xargs -0 -n 200 php8.4 -l | grep -v '^No syntax errors'

• التحليل الساكن. يستطيع PHPStan التحليل على أساس إصدار مستهدف عبر المعامل phpVersion (للإصدار 8.4: phpVersion: 80400). ويفحص معيار PHPCompatibility الخاص بـ PHP_CodeSniffer الشيفرة مقابل testVersion، مثل --runtime-set testVersion 8.4، ومدى تغطية فحوصه يعتمد على الإصدار الذي تثبته.
• الإصلاح الآلي. يستطيع Rector تطبيق كثير من تغييرات الترقية، مثل تحويل الأنواع التي تقبل null ضمنيًا إلى صريحة. اضبط مجموعات PHP عبر ->withPhpSets() في الملف rector.php، واعرض التغييرات أولًا بالأمر vendor/bin/rector process --dry-run، وراجع الفروقات كأي تعديل آخر.
• شغّل مجموعة الاختبارات وتصفح التطبيق على 8.4 مع إظهار رسائل الإهمال: error_reporting = E_ALL وlog_errors = On وdisplay_errors = Off، ثم اقرأ السجل.
• تحقق من المنصة: على الخادم المستهدف يؤكد الأمر composer check-platform-reqs أن إصدار PHP الفعلي وامتداداته تلبي متطلبات الحزم المثبتة.

5. توفير PHP 8.4 على الخادم

• Debian 13: PHP 8.4 هو الإصدار الافتراضي، فثبّت php8.4-fpm وحزم الامتدادات التي تحتاجها.
• Debian 12: يأتي مع 8.2، فإما الانتقال إلى Debian 13 أو استخدام مستودع خارجي لـ 8.4 مع ضبط أولويته حتى لا يستبدل حزمًا أخرى دون قصد.
• Ubuntu 24.04 LTS: يأتي مع 8.3، ويتطلب PHP 8.4 مستودعًا خارجيًا.
• Ubuntu 26.04 LTS: يأتي مع 8.5 لا 8.4، فاستهدف 8.5 على هذا الإصدار.

انتبه إلى الامتدادات المُزالة: لا توجد في الأقسام الرئيسية لـ Debian 13 حزمة امتداد IMAP لـ PHP 8.4، لذا تحتاج التطبيقات التي تستدعي دوال imap_* (عملاء البريد عبر الويب وأدوات جلب بريد الدعم الفني) إلى حل آخر قبل الانتقال. أما php8.4-pspell فمتوفرة في Debian 13 مبنية من امتداد PECL.

sudo apt install php8.4-fpm php8.4-cli php8.4-mysql php8.4-xml php8.4-mbstring php8.4-curl php8.4-intl php8.4-zip php8.4-gd
php8.2 -m > /tmp/mods-82.txt; php8.4 -m > /tmp/mods-84.txt; diff /tmp/mods-82.txt /tmp/mods-84.txt

انسخ إعداداتك أنت فقط: ملفات المجمّعات في /etc/php/8.4/fpm/pool.d/ والتعديلات الصغيرة في conf.d/، ولا تنسخ ملف php.ini الخاص بـ 8.2 كاملًا.

6. التبديل مع إبقاء طريق للعودة

# Nginx
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
sudo nginx -t && sudo systemctl reload nginx

# Apache with PHP-FPM
sudo a2disconf php8.2-fpm && sudo a2enconf php8.4-fpm
sudo apachectl configtest && sudo systemctl reload apache2

# CLI used by cron and workers
php -v
sudo update-alternatives --config php

أبقِ php8.2-fpm عاملًا حتى يتعامل الإصدار الجديد مع حركة حقيقية لفترة، فيصبح التراجع تعديل سطر واحد وإعادة تحميل. أعد تشغيل عمّال الطوابير والمجدولات ليستخدموا الملف التنفيذي الجديد، وعندما يستقر كل شيء أزل حزم 8.2.

ما الذي ينبغي فعله

• رقِّ إطار العمل، وأزل العوائق التي يعرضها composer prohibits php 8.4.
• أصلح المعاملات التي تقبل null ضمنيًا وبقية إهمالات 8.3 و8.4، مستعينًا بـ Rector والتحليل الساكن لتسريع العمل.
• تأكد أن كل امتداد تحتاجه، وخاصة IMAP، متوفر لـ 8.4 على منصتك.
• اختبر على نسخة تجريبية مع تسجيل كامل للأخطاء، ثم بدّل مقبس FPM مع إبقاء الإصدار القديم جاهزًا.
• أنجز ذلك قبل 31 ديسمبر 2026، حين يتوقف PHP 8.2 عن تلقي إصلاحات الأمان من المشروع الأصلي.

المصادر

• php.net/manual/en/migration83.incompatible.php
• php.net/manual/en/migration83.deprecated.php
• php.net/manual/en/migration83.other-changes.php
• php.net/manual/en/migration84.incompatible.php
• php.net/manual/en/migration84.deprecated.php
• php.net/manual/en/migration84.removed-extensions.php
• php.net/supported-versions.php
• php.net/manual/en/features.commandline.options.php
• getcomposer.org/doc/03-cli.md#prohibits-why-not
• getcomposer.org/doc/03-cli.md#check-platform-reqs
• phpstan.org/config-reference#phpversion
• github.com/PHPCompatibility/PHPCompatibility
• getrector.com/documentation
• getrector.com/documentation/set-lists
• packages.debian.org/trixie/php
• packages.debian.org/trixie/php8.4-pspell
• qa.debian.org/madison.php?package=php-imap&text=on
• people.canonical.com/~ubuntu-archive/madison.cgi?package=php&text=on
• salsa.debian.org/php-team/php/-/blob/debian/main/8.4/debian/php-fpm.conf
• salsa.debian.org/php-team/php/-/blob/debian/main/8.4/debian/php-cli.postinst.extra