PIE 1.5: تثبيت إضافات PHP في CI وDocker بأمر واحد

PIE 1.5 يتيح تثبيت إضافات PHP المتعددة بأمر واحد مع pie upgrade واختيار حزمة صريح. إليك الجديد وما قد يكسر بناء CI وDocker لديك.

إن كنت تبني صور Docker أو سكربتات CI لتطبيق Laravel، فتثبيت إضافات PHP عبر PIE صار أقرب إلى سير عمل Composer، لكن مع تغيير في البناء غير التفاعلي قد يكسر سكربتاتك القديمة. يشرح هذا المقال ما الجديد وكيف تتكيّف معه.

ما هو PIE ولماذا يهمّ مطوّر Laravel؟

PIE اختصار لـ PHP Installer for Extensions، وهو أداة سطر أوامر لتثبيت إضافات PHP المكتوبة بـ C مثل redis وxdebug وamqp، وتوفّر وثائقه أوامر مقابلة لأوامر PECL (مثل pie search مقابل pecl search). تظهر أهميته في ملف composer.json نفسه: حين تكتب "ext-redis": "^6.3" فأنت تعلن متطلب تشغيل فقط، ولا يثبّت Composer الإضافة. هنا يأتي دور PIE في بيئة الإنتاج وصور Docker.

بحسب الإعلان الرسمي على موقع PHP Foundation، استغرق تطوير سلسلة 1.5 نحو خمسة أشهر. وتُظهر صفحة الإصدار على GitHub أن 1.5.0 صدر بتاريخ 16 سبتمبر، بينما نُشر إعلان المؤسسة في 7 أكتوبر 2026، وتناولته Laravel News في 2 نوفمبر. لذلك قد تختلف التواريخ بحسب المصدر الذي تقرأه.

أبرز الجديد في PIE 1.5

1. تثبيت عدة إضافات بأمر واحد

بدل تكرار الأمر لكل إضافة، يمكنك كتابة الحزم معًا. المثال التالي من توثيق الإصدار نفسه:

pie install php-amqp/php-amqp:^2.2 girgias/csv

يوجّه PIE خيارات ./configure الخاصة بكل إضافة إلى مكانها الصحيح تلقائيًا. ويذكر الإعلان أن هذه الميزة مفيدة لإعداد صور Docker.

2. pie upgrade

يحدّث هذا الأمر كل الإضافات التي ثبّتها PIE ضمن القيد الذي ثُبّتت به. فإن ثبّتّ foo/bar:^1.0 ينتقل إلى 1.1.0 عند صدوره، لكنه لا يقفز إلى 2.0.0. وللانتقال إلى إصدار رئيسي جديد تعيد التثبيت بقيد جديد:

pie install foo/bar:^2.0

الأمر لا يلمس حزم vendor الخاصة بتطبيقك، بل الإضافات فقط.

3. pie search وpie check-build-tools

يساعدك pie search على معرفة اسم الحزمة قبل كتابة أمر التثبيت:

pie search xdebug
# xdebug/xdebug (provides extension: xdebug)

أما pie check-build-tools فيتحقق من توفر أدوات البناء المطلوبة قبل أن تبدأ عملية التثبيت، وهذا يوفر عليك فشل البناء بعد دقائق من الانتظار.

4. تثبيت متطلبات المشروع مع --no-dev و--select

حين تشغّل pie install بلا وسائط داخل مشروع PHP، يفحص PIE الإضافات المطلوبة في composer.json ويعرض حزمًا مرشّحة للإضافات الناقصة. الجديد في 1.5:

  • --select=extension=package لتحديد الحزمة المقابلة لكل إضافة ناقصة دون أسئلة تفاعلية، مع كتابة اسم الإضافة بلا بادئة ext-.
  • --no-dev لتجاهل الإضافات المذكورة في require-dev فقط، مثل xdebug في بناء الإنتاج.

5. تحسينات أمان وتحقق

وسّع الفريق التحقق المبني على Sigstore لأداة PIE نفسها، وأصبحت مكتبة attestation المستخدمة غير مرتبطة بشهادات GitHub وحدها، مع بقائها الإعداد الافتراضي. ولاحظ أن الإصدار 1.5.5 (30 أكتوبر) يتضمن إصلاحًا أمنيًا مرتبطًا بالإشعار GHSA-4538-pqqf-mv67، وقد صدر الإصلاح نفسه في 1.4.12؛ فاحرص على استخدام أحدث إصدار فرعي وليس 1.5.0 تحديدًا.

أشياء قد تفهمها خطأً عن PIE

  • ext-redis في composer.json لا يثبّت PhpRedis. هو يعلن متطلب تشغيل فقط، والتثبيت الفعلي مسؤولية PIE أو صورة Docker.
  • أدوات البناء لا تُثبَّت تلقائيًا في الوضع غير التفاعلي ما لم تطلب ذلك صراحةً، لذلك يفيدك pie check-build-tools لاكتشاف النقص مبكرًا في خط البناء.
  • إعادة تثبيت إضافة تم التحقق منها لم تعد تعيد العمل، إذ ذكرت ملاحظات الإصدار أن إعادة تثبيتها أصبحت عملية بلا أثر (no-op)، وهذا يفيد عند إعادة تشغيل البناء.
  • توجد أوامر وخيارات أخرى في 1.5 مثل pie install --from-lock وخيار --suppress-download-url-method، لكن ملاحظات الإصدار لا تشرحها بالتفصيل، فارجع إلى الوثائق قبل استخدامها.
  • الأمر يخص إضافات PHP وليس حزم Composer. لا يحدّث pie upgrade مجلد vendor ولا إطار Laravel نفسه.

التغيير الذي قد يكسر بناءك

كان الخيار --allow-non-interactive-project-install هو الطريقة القديمة لاختيار الحزم تلقائيًا للإضافات الناقصة. تقول وثائق الاستخدام الخاصة بـ 1.5 إن هذا الخيار لم يعد يعمل، وإن اختيار الحزم صار مطلوبًا. أي أن البناء غير التفاعلي الذي يعتمد على تثبيت متطلبات المشروع سيفشل إن كانت هناك إضافة ناقصة بلا --select مقابل لها، بحسب ما أوردته Laravel News.

لاحظ أن الإعلان الرسمي لا يسرد هذا ضمن "breaking changes"، لذا راجع وثائق الاستخدام بنفسك قبل الترقية. التغيير يخص تثبيت متطلبات المشروع فقط؛ أما pie install phpredis/phpredis الذي يسمّي الحزمة صراحةً فلا يتأثر.

الإصلاح العملي

لبناء إنتاج يحتاج redis فقط:

pie install --no-interaction --no-dev --select=redis=phpredis/phpredis

ولبيئة تطوير تحتاج redis وxdebug:

pie install --no-interaction \
  --select=redis=phpredis/phpredis \
  --select=xdebug=xdebug/xdebug

كيف تتبنّاه في مشروعك؟

  1. ابحث في Dockerfile وسكربتات CI عن --allow-non-interactive-project-install واستبدله بقيم --select صريحة.
  2. أضف --no-dev في بناء الإنتاج حتى لا تُثبَّت إضافات التطوير.
  3. اجمع أوامر التثبيت المتتالية في أمر واحد لتبسيط الطبقات.
  4. جرّب pie upgrade على بيئة اختبار أولًا، وراقب قيود الإصدارات التي ثبّتّ بها كل إضافة.
  5. ثبّت إصدار PIE في بناءك بدل الاعتماد على "الأحدث" دون ضبط، حتى تتحكم في موعد الترقية.

الخلاصة

PIE 1.5 يجعل إدارة إضافات PHP أكثر قابلية للتكرار: أمر واحد لعدة إضافات، وترقية ضمن القيود، وبحث مدمج. الثمن الوحيد تقريبًا هو أن البناء الآلي يجب أن يسمّي الحزمة المقصودة لكل إضافة بوضوح، وهذا في رأيي أوضح وأكثر قابلية للتتبّع من اختيار الحزم تلقائيًا. راجع سكربتات البناء اليوم قبل أن تفاجئك الترقية في آخر مرحلة من خط النشر.

المصادر