كيفية تحميل إضافات PHP الخارجية في ServBay

يُعد ServBay بيئة تطوير ويب محلية قوية تأتي مزودة مسبقًا بالعديد من ملحقات PHP الشائعة. عادةً يمكن للمستخدم تفعيل الملحقات وتكوينها من خلال الحزم (Packages) -> اللغات (Languages) -> نسخة PHP -> الملحقات داخل ServBay.

لكن أحيانًا يحتاج المطورون إلى تحميل ملحقات PHP خارجية أو مخصصة التجميع غير المضمنة افتراضيًا في ServBay. في هذا الدليل سنشرح بالتفصيل كيفية تحميل مثل هذه الإضافات لنسخة معينة من PHP داخل ServBay، مع استخدام ionCube Loader كمثال عملي. ينطبق هذا الشرح كذلك على أي ملحقات Zend أخرى أو ملفات ملحق .so التي تقوم بتجميعها بنفسك.

ملاحظة هامة حول ملحقات Zend: يعد ionCube Loader أحد ملحقات Zend التي تتكامل بعمق مع محرك Zend الخاص بـ PHP. ولهذا، عند إعداد هذا الملحق يجب استخدام الأمر zend_extension وليس الأمر التقليدي extension المستخدم للأغلب الملحقات الأخرى. تأكد من التمييز بينهما واستخدام الأمر الصحيح.

المتطلبات الأساسية

• تم تثبيت ServBay ويعمل على نظام macOS لديك.
• تمتلك صلاحيات المدير للوصول إلى ملفات النظام وواجهة إعدادات ServBay.
• لديك خبرة باستخدام تطبيق "الطرفية" (Terminal) في macOS.
• حددت ملف ملحق PHP (عادة يكون .so) المطلوب تحميله وهو متوافق مع إصدار PHP المستهدف على ServBay من حيث الإصدار، والمعمارية (إنتل أو Apple Silicon)، وخيارات التجميع (NTS/ZTS).

انتبه: التوافق المعماري أمر بالغ الأهمية

يوفر ServBay حزم PHP أصلية لكل من معماريات Intel (x86_64) وApple Silicon (ARM64، كمعالجات M1/M2/M3/M4). عند تحميل أي ملف ملحق .so، تأكد دائمًا أن المعمارية التي جُمِّع بها الملحق مماثلة تمامًا لمعمارية حزمة PHP المستَخدمة في ServBay.

لا يمكن خلط الملفات متعددة المعماريات. الاختلاف في المعمارية سيؤدي إلى تعذر تشغيل PHP أو حدوث أعطال.

يمكنك استخدام الأمر file للتحقق من معمارية الملف التنفيذي أو ملف الملحق .so:

1. تحقق من معمارية حزمة PHP المرفقة مع ServBay (استبدل 8.3 بنسخة PHP التي تستخدمها):

   file /Applications/ServBay/package/php/8.3/current/bin/php

   النموذج المتوقع للإخراج:

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # يشير إلى معمارية Apple Silicon ARM64

   أو

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # يشير إلى معمارية Intel x86_64

2. تحقق من معمارية ملحق .so الذي قمت بتحميله أو تجميعه (استبدل xdebug.so باسم ملحقك):

   file xdebug.so

   النموذج المتوقع للإخراج:

   xdebug.so: Mach-O 64-bit bundle arm64 # يشير إلى معمارية Apple Silicon ARM64

   أو

   xdebug.so: Mach-O 64-bit bundle x86_64 # يشير إلى معمارية Intel x86_64

   تأكد من تطابق المعمارية بين الخطوتين السابقتين 1 و2 بشكل كامل.

الخطوات العملية

الخطوة 1: تحميل ملف الملحق الخارجي (مثال ionCube Loader)

1. قم بزيارة صفحة تحميل ionCube Loader الرسمية. اختر الإصدار المناسب لمعمارية جهازك. إذا كنت تستخدم macOS ARM64 (سلسلة شرائح Apple M)، حمل نسخة Darwin ARM64. يمكنك استخدام الرابط التالي مباشرة (راجع دائمًا وجود إصدارات أحدث في الموقع الرسمي؛ الرابط التالي مثال فقط): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. بعد التحميل، ستحصل على ملف مضغوط بصيغة .tar.gz، مثل ioncube_loaders_dar_arm64.tar.gz.

الخطوة 2: تحديد نسخة PHP المستهدفة ومسار تثبيت الملحقات في ServBay

1. افتح تطبيق ServBay.

2. من الشريط الجانبي الأيسر، اختر الحزم (Packages) ثم اللغات (Languages).

3. من القائمة على اليمين، حدد نسخة PHP التي ترغب بتثبيت ionCube Loader لها (مثلاً في هذا الشرح PHP 8.3). دوّن رقم الإصدار.

4. حدد مسار تثبيت ملحقات PHP (extension_dir) لتلك النسخة في ServBay. هذا هو المسار الافتراضي لحفظ ملفات الملحق .so. غالبًا ما يكون هذا المسار مرتبطًا بمكان تثبيت ServBay وإصدار PHP وخيارات التجميع.

   للحصول على المسار الصحيح، استخدم الأمر التالي في الطرفية:

   افتح تطبيق الطرفية وأدخل الأمر التالي (استبدل /Applications/ServBay/package/php/8.3/current/bin/php بمسار ملف php القابل للتنفيذ الخاص بإصدارك المستهدف):

   /Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir

   سيظهر لك مسار extension_dir => /path/to/extension/directory. كمثال:

   extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831

   احتفظ بهذا المسار لاستخدامه لاحقًا.

الخطوة 3: فك وضبط ملف Loader

1. افتح الطرفية.

2. استخدم أمر cd للانتقال لمجلد التحميلات (غالبًا ~/Downloads):

   cd ~/Downloads

3. لفك الضغط:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   سينشأ مجلد جديد باسم ioncube.

4. ادخل إلى المجلد:

   cd ioncube

5. ستجد ملفات .so متنوعة لكل نسخة PHP، مثل ioncube_loader_dar_8.3.so. حدد الملف المطابق لنسخة PHP المستهدفة (مثلاً 8.3).

6. انسخ الملف المحدد إلى مسار تثبيت الملحقات الذي حصلت عليه في الخطوة 2. كمثال إذا كان المسار هو /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/:

   cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/

   • استبدل المسار في الأمر السابق بالمسار الفعلي الخاص بك الذي حصلت عليه من الأمر php -i.
   • تأكد أن الملف الذي تنسخه متطابق تمامًا مع نسخة PHP ومعماريتها.

الخطوة 4: إعداد PHP ضمن ServBay

1. عد إلى واجهة ServBay.

2. تأكد من اختيار اللغات (Languages)، ثم اختر نسخة PHP المراد تكوينها (مثلاً PHP 8.3).

3. ضمن تكوين النسخة على اليمين، انتقل إلى تبويب PHP.

4. مرر للأسفل حتى تجد مربع معاملات إضافية (Additional Parameters).

5. أضف سطر الإعداد التالي لتحديد اسم ملف ionCube Loader:

   zend_extension = ioncube_loader_dar_8.3.so

   • هام: استبدل اسم الملف باسم ملف .so الفعلي الذي نسخته.
   • استخدم zend_extension وليس extension، لأن ionCube هو ملحق Zend.
   • ما دمت قد وضعت الملف تحت extension_dir، يكفي وضع الاسم فقط دون المسار الكامل.
   • إذا كان هناك إعدادات أخرى، أضف هذا الأمر في سطر جديد.

   (الصورة لأغراض التوضيح، قد يختلف الشكل حسب الإصدار)

6. اضغط زر حفظ (Save) أسفل يمين الواجهة.

الخطوة 5: إعادة تشغيل خدمة PHP

بعد الضغط على زر حفظ (Save)، سيكتشف ServBay التعديلات تلقائيًا وسيعيد تشغيل الخدمة ذات الصلة بما فيها PHP. عادةً لا تحتاج لاتخاذ خطوات إعادة تشغيل إضافية يدويًا.

الخطوة 6: التحقق من تحميل الملحق بنجاح

هناك طريقتان شائعتان للتحقق من نجاح تحميل ionCube Loader:

1. عن طريق الطرفية:

   • افتح الطرفية.

   • شغل الأمر التالي لعرض ملحقات PHP المحملة (استعمل المسار الكامل لـ PHP الخاص بنسختك):

     /Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube

     إذا نجحت العملية ستظهر لك نتيجة مثل ionCube Loader.

   • يمكنك أيضًا تنفيذ أمر php -v لرؤية معلومات النسخة، ويظهر عادةً سطر ionCube Loader تحت معلومات محرك Zend:

     /Applications/ServBay/package/php/8.3/current/bin/php -v

     مثال إخراج بعد التحميل:

     PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
     Copyright (c) The PHP Group
     Zend Engine v4.3.16, Copyright (c) Zend Technologies
         with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.

     لاحظ السطر with the ionCube PHP Loader ....

2. عن طريق استخدام الدالة phpinfo():

   • أنشئ في جذر موقعك (كمثال /Applications/ServBay/www/servbay.demo/ أو المسار الذي تستخدمه) ملف PHP جديد، مثل info.php.
   • ضَع بداخله:

     <?php
     // إظهار جميع معلومات إعداد PHP
     phpinfo();
     ?>

   • استعرض الملف عبر المتصفح كـ http://servbay.demo/info.php (استبدل باسم نطاقك المحلي).
   • في صفحة phpinfo() استخدم البحث في المتصفح (عادةً Ctrl+F أو Cmd+F) وابحث عن "ionCube". سترى قسم خاص بالملحق مع معلومات الإصدار والتراخيص إذا تم تحميله بالفعل.

إذا ظهرت معلومات ionCube Loader بالتحقق، فهذا يعني أن الملحق تم تحميله بنجاح.

الأسئلة الشائعة وحلول المشاكل

• فشل تشغيل PHP أو حدوث أعطال: السبب الشائع هو عدم تطابق معمارية ملف الملحق مع معمارية PHP. تأكد من التوافق تمامًا حسب الخطوات في المتطلبات الأساسية. كذلك قد تؤدي اختلاف إصدارات PHP أو خيارات التجميع إلى مشاكل.
• خطأ في مسار extension_dir: تأكد من أنك نسخت ملف .so إلى المسار الفعلي الصحيح الموجود باستخدام أمر php -i | grep extension_dir.
• أخطاء في أوامر التكوين: راجع التعليمات المضافة في معاملات إضافية في ServBay. لملاحق Zend استخدم دائمًا zend_extension = filename.so، أما الملحقات العادية فـ extension = filename.so. اسم الملف يجب أن يطابق الملف المنسوخ بالضبط (حساس لحالة الأحرف).
• مشكلة في صلاحيات الملفات: تأكد أن المستخدم الذي يعمل به ServBay (غالبًا مستخدم macOS الخاص بك) لديه صلاحية قراءة ملف .so والمجلد. غالبًا لا توجد مشاكل إلا إذا غيرت الصلاحيات يدويًا.
• عدم إعادة تشغيل ServBay: غالبًا يتم إعادة التشغيل تلقائيًا، لكن إذا لم ترى التغييرات جرب إعادة تشغيل الخدمة من الواجهة أو أعد تشغيل تطبيق ServBay بالكامل.
• عدم ظهور معلومات الملحق في phpinfo(): تأكد أنك تعرض ملف phpinfo() على الموقع الصحيح ومع نسخة PHP الصحيحة التي أضفت إليها التكوين.

الخلاصة

بتنفيذ الخطوات التفصيلية السابقة، ستتمكن من تحميل ionCube Loader أو أي ملحق PHP خارجي آخر بصيغة .so لنسخة معينة ضمن ServBay بنجاح. الأهم هو تحديد إصدار PHP المستهدف بدقة، والبحث عن مسار تثبيت الملحق الصحيح (extension_dir)، ووضع ملحق متوافق مع المعمارية المطلوبة هناك، ثم ضبط التعليمات اللازمة ضمن معاملات إضافية باستخدام الأمر المناسب (zend_extension أو extension). إذا صادفتك أي مشاكل راجع قسم حلول المشاكل بدقة، خاصةً توافق المعمارية والمسارات.