استخدام XDebug لتصحيح أخطاء مشاريع PHP

يُعتبر XDebug أداة قوية لتصحيح الأخطاء، تحليل الأداء، وتغطية الشيفرة في تطوير PHP. يُمكنك عبر دمج واستخدام XDebug في بيئة التطوير المحلية ServBay رفع كفاءة تطوير مشاريع PHP وجودة الشيفرة بشكل ملحوظ. يمنحك XDebug القدرة على ضبط نقاط التوقف (Breakpoints)، فحص قيم المتغيرات، تتبع مكدس استدعاء الدوال، وتحليل عنق الزجاجة في الأداء، ما يساعدك على تحديد المشكلات وحلها بشكل أكثر فعالية.

مقدمة عن XDebug

XDebug هو إضافة (Extension) مصممة خصيصًا للغة PHP، تزوّدك بقدرات هائلة في التصحيح والتحليل. يدعم التصحيح عن بُعد (عادةً عبر بروتوكول DBGp)، إعداد نقاط التوقف، التنفيذ خطوة بخطوة، فحص قيم المتغيرات، تتبع مكدس استدعاء الدوال، تحليل أداء السكريبت (Profiling)، وتوليد تقارير تغطية الشيفرة (Coverage). يوفر لك XDebug رؤية معمّقة في سير تنفيذ الشيفرة وحالتها، ما يمكّنك من تحديد وإصلاح الأخطاء بكفاءة أكبر.

يدعم XDebug عدة أوضاع عمل، وأكثرها شيوعًا هو وضع debug المخصّص لتصحيح الأخطاء التفاعلي عبر نقاط التوقف.

تفعيل وتكوين XDebug في ServBay

يأتي ServBay مُثبتًا مُسبقًا بإضافة XDebug لكل إصدار من إصدارات PHP المدعومة، فلا داعي لتحميل أو تجميع الإضافة يدويًا.

1. تفعيل وحدة XDebug: افتح واجهة تطبيق ServBay. انتقل إلى اللغة-PHP، وحدد إصدار PHP الذي ترغب باستخدام XDebug معه. في قسم الإضافات، ابحث عن وحدة xdebug وتأكد أن حالتها "مفعلة". إذا لم تكن مفعّلة، انقر على زر التفعيل. قد تحتاج إلى إعادة تشغيل خدمة PHP-FPM بعد التفعيل (عادةً يقوم ServBay بذلك تلقائيًا).

2. تكوين بيئة التطوير المتكاملة (IDE): في بيئة التطوير المتكاملة التي تستخدمها مثل PHPStorm أو VS Code، اضبط الاتصال بـ XDebug. غالبًا ما يتضمن ذلك تعيين منفذ الاستماع (متوافق مع إعدادات XDebug في الواجهة)، وربما إعداد تخطيط المسارات البعيدة (في حال اختلف مسار المشروع محليًا عن الخادم، مع العلم أن ذلك غالبًا غير مطلوب في بيئة ServBay المحلية).

   المزيد من تفاصيل إعدادات IDE

   للحصول على خطوات مفصّلة حول كيفية إعداد XDebug في بيئات تطوير معينة مثل PHPStorm وVS Code وغيرهما، يرجى مراجعة مستندات الـIDE المعنية أو الرجوع إلى كيفية تفعيل وحدة Xdebug المدمجة في ServBay.

مثال عملي: تصحيح مشروع PHP باستخدام XDebug في ServBay

سنوضح كيفية استخدام XDebug في ServBay من خلال مثال مشروع بسيط.

1. إعداد موقع ServBay

ابدأ بإنشاء موقع جديد في ServBay لاستضافة مشروعك التجريبي:

1. أنشئ مجلد مشروع جديد داخل الدليل الجذري لمواقع ServBay /Applications/ServBay/www/، على سبيل المثال servbay-xdebug-app.
2. افتح واجهة تطبيق ServBay وانتقل إلى قسم "المواقع".
3. أضف موقعًا جديدًا، وعيّن الدليل الجذري إلى /Applications/ServBay/www/servbay-xdebug-app.
4. اختر اسم نطاق محلي مثل servbay-xdebug-app.servbay.demo.
5. اختر إصدار PHP المرغوب واكّد أن XDebug مفعل له كما ذكر سابقًا.
6. احفظ وطبّق التغييرات. سيقوم ServBay تلقائيًا بضبط Caddy/Nginx وتحديث ملف hosts (أو استخدام DNS الخاص بـ ServBay).

2. هيكل المشروع والكود البرمجي

أنشئ الملفات والمجلدات التالية ضمن /Applications/ServBay/www/servbay-xdebug-app/:

servbay-xdebug-app/
├── src/
│   └── Calculator.php
└── index.php

محتوى ملف src/Calculator.php:

<?php
namespace App;

class Calculator
{
    public function add($a, $b)
    {
        // ضع نقطة توقف عند هذا السطر
        return $a + $b;
    }

    public function subtract($a, $b)
    {
        return $a - $b;
    }
}

محتوى ملف index.php:

<?php
// لنفترض أنك تستخدم Composer، هنا يتم تحميل الـ autoloader
// إذا لم تكن تستخدم Composer، عدّل طريقة التحميل حسب الحاجة
require __DIR__ . '/vendor/autoload.php';

use App\Calculator;

echo "Debugging Example:\n";

$calculator = new Calculator();
$num1 = 5;
$num2 = 3;

$sum = $calculator->add($num1, $num2);
$difference = $calculator->subtract($num1, $num2);

echo "Sum: " . $sum . "\n";
echo "Difference: " . $difference . "\n";

echo "Done.\n";
?>

ملاحظة: السطر require __DIR__ . '/vendor/autoload.php'; يفترض أنك تستخدم Composer. إذا كنت تقوم بتجربة بسيطة، تستطيع حذف هذا السطر واستبدال السطر use App\Calculator; بـ require __DIR__ . '/src/Calculator.php';.

3. ضبط نقاط التوقف

افتح ملف /Applications/ServBay/www/servbay-xdebug-app/src/Calculator.php داخل IDE الذي تستخدمه (مثل PHPStorm)، وانقر بجوار سطر return $a + $b; داخل دالة add لضبط نقطة توقف.

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

1. في الـIDE الخاص بك، فعّل خيار الاستماع لاتصالات XDebug. في PHPStorm، يكون ذلك بالنقر على زر "بدء الاستماع لاتصالات تصحيح PHP" (أيقونة سماعة الهاتف أو حشرة صغيرة) في شريط الأدوات العلوي.
2. في المتصفح، انتقل إلى ملف index.php على موقع ServBay الخاص بك: https://servbay-xdebug-app.servbay.demo/index.php.
3. إذا كانت قيمة إعداد xdebug.start_with_request هي trigger، تأكد من إضافة مشغّل XDebug (Trigger) عبر إضافة متصفح أو يدويًا (مثلاً، استخدم الرابط https://servbay-xdebug-app.servbay.demo/index.php?XDEBUG_TRIGGER=1).

5. عملية التصحيح

1. عند زيارة index.php في المتصفح وتفعيل جلسة XDebug، يتم الاتصال بـIDE تلقائيًا وإيقاف التنفيذ عند نقطة التوقف المضبوطة.
2. سيعرض الـIDE وضع التصحيح مشيرًا إلى توقف الكود عند السطر المناسب في دالة add بملف Calculator.php.

6. فحص قيم المتغيرات

1. من نافذة التصحيح في IDE، يمكنك رؤية الكود الحالي، مكدس الاستدعاء (Call Stack)، وقيم المتغيرات.
2. ضمن لوحة "Variables"، ستتمكن من فحص قيم المتغيرات ضمن النطاق الحالي. مثلاً، يجب أن ترى أن قيمة $a هي 5 وقيمة $b هي 3.

7. التنفيذ خطوة بخطوة

1. استخدم أزرار التنفيذ خطوة بخطوة في IDE (عادة: Step Over (F8), Step Into (F7), Step Out (Shift+F8)) لتتبع سير التنفيذ:
   • Step Over: ينفذ السطر الحالي بالكامل، وإذا اشتمل على دالة لا يدخل في تفاصيلها بل ينتقل للسطر التالي بعد إتمامها.
   • Step Into: يدخل داخل الدوال عند تنفيذها لينقلك للسطر الأول داخل الدالة.
   • Step Out: يكمل تنفيذ الدالة الحالية ويعود لموضع الاستدعاء الأصلي.
2. بذلك تستطيع تتبع تغيّر قيم المتغيرات وسير التنفيذ سطرًا بسطر.

8. مواصلة التنفيذ

1. انقر على زر "استئناف التنفيذ" في IDE (عادةً أيقونة تشغيل خضراء أو F9) ليواصل البرنامج التنفيذ حتى نقطة التوقف التالية أو حتى نهاية التنفيذ.

9. عرض النتائج

1. بعد انتهاء التنفيذ، يمكنك معاينة المخرجات في المتصفح (أو التيرمنال إذا كنت تصحح أوامر CLI). ستلاحظ ناتجًا مثل التالي:

   Debugging Example:
   Sum: 8
   Difference: 2
   Done.

ملاحظات هامة

• جدار الحماية: تأكد أن جدار الحماية في نظام التشغيل لا يمنع الاتصالات على المنفذ الذي يستمع عليه IDE (الافتراضي 9003).
• تعارض المنافذ: تأكد أن منفذ XDebug غير مستخدم من تطبيقات أخرى.
• تأثير الأداء: إذا كان الإعداد xdebug.mode=debug و xdebug.start_with_request=yes، سيحاول كل طلب PHP بدء جلسة تصحيح، ما قد يؤثر سلبيًا على أداء الموقع. عند عدم الحاجة للتصحيح، قم بتعطيل XDebug أو اضبط xdebug.start_with_request إلى trigger.
• تصحيح سكريبتات CLI: يمكن استعمال XDebug لتصحيح نصوص (سكريبتات) PHP من سطر الأوامر. ستحتاج لضبط متغيرات البيئة (Environment Variables) أو استخدام معلمات محددة. راجع وثائق XDebug الرسمية لذلك.
• إصدارات وتكوينات IDE: قد تختلف واجهات وضبط إعدادات IDE من إصدار لآخر. راجع الوثائق الرسمية لأداتك للحصول على التفاصيل الدقيقة.

الأسئلة المتكررة (FAQ)

س: لا يستطيع IDE الاتصال مع XDebug، ما الحل؟

ج: تحقّق من النقاط التالية:

1. تأكد أن وحدة XDebug مفّعلة للإصدار المناسب من PHP في ServBay.
2. افحص إعدادات xdebug.mode، وxdebug.client_host، وxdebug.client_port في ملف php.ini وتأكد تطابقها مع إعدادات الاستماع في IDE.
3. إذا كنت تستخدم xdebug.start_with_request = trigger، تحقق من أنك أضفت المشغّل (Trigger) بشكل صحيح (GET/POST/كوكي/هيدر).
4. تأكد أن جدار الحماية يسمح بمرور البيانات عبر منفذ XDebug.
5. تحقق أن IDE يستمع فعلاً على نفس المنفذ.

س: لماذا أصبح موقعي بطيئًا جدًا بعد تفعيل XDebug؟

ج: السبب الأرجح هو تعيين إعداد xdebug.start_with_request إلى "yes". حيث يحاول كل طلب PHP فتح جلسة تصحيح مما يبطئ التنفيذ. ينصح بضبطه كـ trigger لتفعيل التصحيح فقط عند الحاجة.

س: هل أستطيع تصحيح طلبات AJAX عبر XDebug؟

ج: نعم، يمكنك ذلك. تعامل جلسات تصحيح AJAX كما هو الحال مع الطلبات HTTP العادية، فقط تأكد من تضمين مشغّل XDebug ضمن الطلب (غالبًا عن طريق تعيين كوكي أو هيدر).

س: هل يدعم XDebug في ServBay محررات أخرى غير PHPStorm مثل VS Code؟

ج: نعم. XDebug المدمج مع ServBay هو إضافة قياسية للـPHP وتدعم أي IDE يتوافق مع بروتوكول DBGp، بما يشمل VS Code (مع إضافة PHP Debug)، NetBeans، Eclipse، إلخ. طريقة الإعداد متشابهة. فقط تأكد من ضبط منفذ الاستماع داخل الـIDE.

الخلاصة

يمكّن XDebug المدمج مع ServBay المطورين من تصحيح مشاريع PHP بكفاءة عالية في بيئتهم المحلية. إتقان توزيع نقاط التوقف، فحص المتغيرات، والتنفيذ خطوة بخطوة سيساعدك على تحديد وإصلاح المشكلات بسرعة ويضمن جودة الشيفرة. ومع ميزة إدارة بيئة التطوير في ServBay، سيصبح XDebug أداة لا غنى عنها في سير عمل تطوير PHP. ابدأ اليوم باستخدام XDebug على ServBay واستمتع بتجربة تطوير PHP أكثر سلاسة وفعالية!