كيفية تفعيل وتكوين وحدة Xdebug في ServBay

يقدّم ServBay كبيئة تطوير ويب محلية قوية تجربة متكاملة لمطوري PHP؛ إذ يأتي مزودًا مسبقًا بأداة التصحيح والتحليل Xdebug. تفعيل Xdebug يمكن أن يحسن بشكل كبير من إنتاجية تطوير تطبيقات PHP، إذ يتيح لك إجراء التصحيح البرمجي، وتحليل الأداء، وكشف نطاق التغطية البرمجية بسهولة أكبر. في هذا المقال ستتعرف بالتفصيل على كيفية تفعيل وتكوين Xdebug في ServBay، وكيفية ربطه مع أشهر بيئات التطوير المتكاملة (IDEs).

نظرة عامة على وحدة Xdebug

Xdebug هو امتداد PHP متكامل الوظائف صُمّم خصيصًا لتصحيح وتنميط كود PHP. يحتوي ServBay مسبقًا على Xdebug، ما يغنيك عن الحاجة للتركيب اليدوي أو التهيئة المعقدة، ويجعل التفعيل والإعداد أمرًا بسيطًا للغاية.

المزايا الرئيسية لـ Xdebug

• تصحيح باستخدام نقاط التوقف: يتيح لك وضع نقاط توقف عند أسطر محددة من الشيفرة، فيتوقف التنفيذ عند مرور البرنامج بها، ويمكنك في هذا الوقت فحص قيم المتغيرات وسجلات الاستدعاءات خطوة بخطوة.
• التنفيذ خطوة بخطوة: يدعم تنفيذ السطر الحالي (Step Over)، الدخول في الدوال (Step Into)، والخروج منها (Step Out) لتتبع سير عمل البرنامج بوضوح.
• مراقبة المتغيرات: خلال جلسة التصحيح يمكنك الاطلاع المباشر على قيم المتغيرات المحلية والعامة في الوقت الحقيقي.
• تتبع الاستدعاءات (Stack Trace): يعرض لك تفصيلاً عن تسلسل الدوال المستدعاة عند حدوث خطأ أو استثناء، لمساعدتك في تحديد مصدر المشكلة بسرعة.
• تحليل الأداء (Profiling): يتيح لك إنتاج تقارير حول أداء الشيفرة البرمجية، لتكتشف عنق الزجاجة في الأداء.
• قياس تغطية الكود (Code Coverage): يقيس نسبة وصول اختباراتك لأجزاء الشيفرة، ما يساعدك في تقييم فعالية الاختبارات والتأكد من الجودة.

نسخ Xdebug المثبتة مسبقًا وتوزيع المنافذ في ServBay

يحتوي ServBay على وحدة Xdebug معدّة مسبقًا لكل إصدار من PHP. يجب الانتباه إلى أن كل إصدار من PHP يستخدم منفذًا مستقلاً لـ Xdebug، مرتبطًا برقم الإصدار، وهذا ضروري جدًا أثناء إعداد التصحيح في IDE.

إصدار PHP	نسخة Xdebug المدمجة	منفذ الاستماع الافتراضي لـ Xdebug
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

قاعدة المنافذ

القاعدة الافتراضية لمنفذ استماع Xdebug هي 39000 + الرقم الثانوي لإصدار PHP. على سبيل المثال، إصدار PHP 8.3 يستخدم المنفذ 39000 + 83 = 39083، بينما إصدار PHP 7.4 هو 39000 + 74 = 39074. فهم هذه القاعدة سيساعدك في تحديد منفذ Xdebug المناسب بسرعة لكل إصدار PHP.

كيفية تفعيل وحدة Xdebug

يمكنك تفعيل Xdebug بسهولة في ServBay، ويوصى بالقيام بذلك عبر واجهة المستخدم الرسومية (GUI). كما يمكنك تفعيله يدويًا عبر تحرير ملفات الإعدادات.

تفعيل Xdebug عن طريق الواجهة الرسومية لـ ServBay

هذه هي الطريقة الأسرع والأسهل عادةً:

1. افتح واجهة تطبيق ServBay.
2. من الشريط الجانبي الأيسر، اختر اللغات.
3. وسّع قسم PHP وابحث عن إصدار PHP الذي ترغب في تفعيل Xdebug عليه، مثلاً PHP 8.3.
4. انقر زر الإضافات بجانب الإصدار المختار.
5. من القائمة المنبثقة، ابحث عن وحدة Xdebug.
6. حرّك مفتاح التفعيل بجانب وحدة Xdebug من وضع الإيقاف إلى التشغيل.
7. عدّل الإعدادات حسب الحاجة.
8. اضغط زر حفظ في أسفل الواجهة.
9. سيقوم ServBay بإعادة تشغيل عمليات PHP تلقائياً وتفعيل الوحدة الجديدة.

توضيح: تفعيل Xdebug ضمن قائمة الإضافات

التحقق من تفعيل وحدة Xdebug بنجاح

أفضل طريقة للتحقق هي باستخدام دالة phpinfo() لاستعراض إعدادات PHP الحالية.

1. أنشئ ملف PHP جديد باسم مثل phpinfo.php ضمن مجلد موقع ServBay الرئيسي (عادةً /Applications/ServBay/www).
2. أضف الكود التالي في الملف:

   <?php
   phpinfo();
   ?>

3. زر الملف عبر متصفحك، مثلاً https://servbay.demo/phpinfo.php (استبدل servbay.demo باسم الدومين الذي أعددته في ServBay).
4. في صفحة phpinfo ابحث عن كلمة "Xdebug". إذا تم تفعيل الوحدة بنجاح ستجد قسمًا منفصلًا لإعدادات Xdebug، به معلومات النسخة والمعاملات.

توضيح: إيجاد معلومات Xdebug في مخرجات phpinfo

إعداد Xdebug للتصحيح ضمن بيئة التطوير

تفعيل Xdebug هو الخطوة الأولى فقط – يحتاج الأمر أيضًا إلى ضبط مفسر PHP، وحدود التصحيح، وتعيين مسارات المشاريع ضمن IDE. سنشرح أدناه خطوات الضبط في كل من PHPStorm وVisual Studio Code.

إعداد Xdebug مع PHPStorm

دعم PHPStorm لـ Xdebug ممتاز ويوفر تجربة تصحيح متقدمة.

1. فتح إعدادات PHPStorm: قم بتشغيل PHPStorm وافتح نافذة الإعدادات من قائمة File -> Settings (ويندوز/لينكس) أو PHPStorm -> Preferences (macOS).

2. تكوين مفسر PHP CLI:

   • انتقل إلى Languages & Frameworks -> PHP.
   • في جزء CLI Interpreter اضغط على زر ....
   • من النافذة المنبثقة اضغط على + لإضافة مفسر جديد.
   • اختر مسار ملف PHP التنفيذي الملائم في ServBay، مثلاً: /Applications/ServBay/package/php/8.3/8.3.7/bin/php (ملاحظة: قد يختلف المسار حسب رقم الإصدار والتثبيت).
   • سيكتشف PHPStorm تلقائياً النسخة والإضافات النشطة (بما فيها Xdebug).
   • اضغط OK لحفظ الإعدادات. توضيح: تكوين مفسر PHP CLI الخاص بـ ServBay في PHPStorm

3. ضبط معلمات التصحيح لـ Xdebug:

   • توجه إلى Languages & Frameworks -> PHP -> Debug.
   • ضمن قسم Xdebug، عيّن القيمة Debug Port إلى منفذ Xdebug المرتبط بإصدار PHP المفعّل على ServBay (مثلاً، PHP 8.3 = 39083). تأكد أن هذا المنفذ متطابق مع إعداد xdebug.client_port.
   • فعل خيار Can accept external connections.
   • اضغط Apply ثم OK للحفظ. توضيح: تحديد منفذ الاستماع لـ Xdebug في PHPStorm

4. إعداد خريطة مسارات ملفات السيرفر:

   • انتقل إلى Languages & Frameworks -> PHP -> Servers.
   • اضغط على علامة + لإضافة خادم جديد.
   • أدخل اسم السيرفر (مثلاً: ServBay Localhost).
   • عيّن Host إلى دومين موقعك في ServBay (مثلاً servbay.demo).
   • أدخل قيمة Port (عادةً 443 لـ HTTPS أو 80 لـ HTTP).
   • اختر Debugger = Xdebug.
   • فعّل خيار Use path mappings.
   • أضبط تعيين المسارات بين مجلد مشروعك المحلي (Absolute path to local source) والمسار المناظر في السيرفر. غالبًا يكون مجلد /Applications/ServBay/www/myproject على جهازك يطابق / على السيرفر الافتراضي. إذا كانت إعدادات الدومين فرعية (مثلاً: https://myproject.servbay.demo/)، فالمسارات غالبًا كما هي.
   • بعد التأكد من الضبط، اضغط OK. توضيح: إعداد السيرفر وتعيين المسارات في PHPStorm

5. بدء جلسة التصحيح:

   • افتح ملف المشروع الخاص بك في PHPStorm.
   • ضع نقطة توقف بالنقر على المساحة بجانب رقم السطر في الكود (ستظهر دائرة حمراء).
   • اضغط أيقونة Start Listening for PHP Debug Connections (أيقونة الخنفساء الصغيرة في الأعلى). تصبح خضراء عند التفعيل وتعني أن PHPStorm مستعد لاستقبال اتصالات Xdebug.
   • افتح تطبيقك عبر المتصفح (مثلاً: https://servbay.demo/index.php).
   • إذا كان كل الضبط صحيحًا، سيوقف Xdebug التنفيذ عند نقطة التوقف وتبدأ جلسة تصحيح تفاعلية في PHPStorm. توضيح: تشغيل وضع الاستماع لـ Xdebug في PHPStorm

إعداد Xdebug في Visual Studio Code (VS Code)

VS Code محرر كود قوي، ودعمه لـ Xdebug ممتاز عبر الامتدادات.

1. تثبيت امتداد PHP Debug:

   • افتح VS Code.
   • انتقل إلى قائمة الامتدادات (Ctrl+Shift+X أو Cmd+Shift+X).
   • ابحث عن "PHP Debug" من Felix Becker وقم بتثبيته.

2. إعداد ملف launch.json:

   • افتح مجلد مشروع PHP لديك.
   • انتقل إلى قائمة التشغيل والتصحيح (Ctrl+Shift+D أو Cmd+Shift+D).
   • اضغط على رمز الترس في الأعلى واختر "PHP"، ما سينشئ ملف launch.json داخل مجلد .vscode.
   • حرّر ملف launch.json وتأكّد من أن قيمة port تعادل منفذ الاستماع لـ Xdebug الخاص بإصدار PHP على ServBay (مثلاً: 39083 لـ PHP 8.3).
   • تكوين تعيين المسارات: هذه خطوة حاسمة. ضمن إعدادات pathMappings، عين مسار المشروع في سيرفر ServBay إلى مجلد المشروع المحلي.

     {
         "version": "0.2.0",
         "configurations": [
             {
                 "name": "Listen for Xdebug",
                 "type": "php",
                 "request": "launch",
                 "port": 39083, // عدل هذا المنفذ حسب إصدار PHP الخاص بك
                 "pathMappings": {
                     // عين مسار المشروع في ServBay إلى مسار جهازك المحلي
                     // كمثال: إذا كان المشروع في /Applications/ServBay/www/myproject
                     // ويتم فتحه عبر https://servbay.demo/، فالجذر '/' يقابل مجلد المشروع المحلي
                     "/": "${workspaceRoot}"
                     // إذا كان مشروعك على دومين فرعي كـ https://myproject.servbay.demo/
                     // فجذر السيرفر '/' يقابل أيضًا مجلد المشروع المحلي
                     // "/": "${workspaceRoot}" // كذلك ينطبق
                 }
             },
             {
                 "name": "Launch currently open script",
                 "type": "php",
                 "request": "launch",
                 "program": "${file}",
                 "cwd": "${fileDirname}",
                 "port": 39083 // عدل حسب إصدار PHP
             }
         ]
     }

     عدل إعدادات pathMappings بما يتوافق مع بنية مشروعك وإعداد موقع ServBay. ${workspaceRoot} عادة ما يشير لجذر مجلد المشروع المفتوح داخل VS Code.

3. بدء جلسة التصحيح:

   • افتح ملف PHP ترغب في تصحيحه في VS Code.
   • ضع نقطة توقف بجانب رقم السطر (دائرة حمراء).
   • انتقل لواجهة التصحيح (Ctrl+Shift+D أو Cmd+Shift+D).
   • من قائمة التهيئات بالأعلى اختر "Listen for Xdebug".
   • اضغط زر التشغيل الأخضر. سيتحول شريط حالة VS Code إلى اللون البرتقالي دلالة على الاستعداد.
   • من المتصفح افتح تطبيقك؛ إذا تم الإعداد بشكل صحيح، سيتوقف التنفيذ عند نقطة التوقف في VS Code.

الأسئلة الشائعة (FAQ)

• س: Xdebug لا يظهر في صفحة phpinfo()؟

  • ج: تحقق أنك فعّلت Xdebug في واجهة ServBay أو بتحرير ملف xdebug.ini.
  • تأكد من إعادة تشغيل خدمة PHP ذات الصلة.
  • تأكد أن مسار ملف xdebug.ini صحيح، وأن سطر zend_extension = xdebug.so غير معلق.
  • راجع سجل الأخطاء error.log في /Applications/ServBay/logs/php/<version>/ بحثًا عن رسائل تتعلق بفشل تحميل Xdebug.

• س: حددت نقطة توقف بالـ IDE لكنها لا تعمل؟

  • ج: تحقق أن IDE في وضع الاستماع لاتصالات Xdebug (أيقونة الخنفساء خضراء في PHPStorm/شريط الحالة برتقالي في VS Code).
  • تأكد من توافق منفذ Xdebug في الإعدادات مع قيمة xdebug.client_port ومع المنفذ الافتراضي للإصدار في ServBay.
  • تحقق من صحة إعدادات تعيين المسارات (Path Mapping) في الـ IDE: ينبغي أن تطابق مسارات ملفات السيرفر المحلي مشروعك تماماً – هذا هو السبب الرئيسي لمشاكل نقاط التوقف.
  • تأكد من إعدادات الجدار الناري أو الحماية وعدم حظر المنفذ (390xx).
  • إذا كنت تستخدم xdebug.start_with_request=trigger في xdebug.ini, تأكد أن الطلب يتضمن مشغل التصحيح (مثل إضافة ?XDEBUG_TRIGGER=1 في عنوان الرابط أو استخدام إضافات المتصفح).

• س: ينقطع اتصال Xdebug بعد فترة؟

  • ج: راجع معلمة xdebug.remote_autostart أو xdebug.start_with_request في xdebug.ini؛ إذا كانت مفعلة دائمة، قد يحاول التصحيح في كل طلب مما يسبب مشاكل. يُنصح باستعمال وضع trigger.
  • تحقق من إعدادات المهلة في IDE.

الخلاصة

بفضل التكامل المسبق وخطوات التكوين السلسة، يوفر ServBay تجربة تشغيل Xdebug لمطوري PHP بسهولة وسرعة. سواءً استخدمت الواجهة الرسومية أو قمت بتحرير الملفات مباشرة، يمكنك تفعيل Xdebug لأي إصدار PHP بسرعة. ومع دعم PHPStorm وVS Code القوي، ستتمكن من تحسين عملية تصحيح الأخطاء وأداء الشيفرة وضبط الجودة بشكل كبير – ما يؤدي لرفع إنتاجيتك كمطور. إتقان استخدام ServBay مع Xdebug سيصنع فرقًا حقيقيًا في سير عمل تطوير PHP محليًا.