Полная и актуальная настройка Xdebug + Open Server + PhpStorm

Инструкция по отладке PHP с Xdebug: шаг за шагом

Xdebug — это мощный PHP-расширитель, который позволяет проводить пошаговую отладку, анализировать переменные, профилировать код и значительно повышать качество приложений. В этой инструкции показано, как настроить его с популярным локальным сервером Open Server и IDE PhpStorm.

---

🚀 Что нужно для начала

✔️ Установлен Open Server с PHP
✔️ Установлен PhpStorm
✔️ Включен модуль Xdebug в PHP
✔️ Базовые знания PHP и IDE

---

📌 1. Настройка Xdebug в Open Server

В Open Server Xdebug может быть уже установлен, но нужно правильно включить и сконфигурировать его для современной версии (Xdebug 3.x).

1. Откройте в Open Server настройки PHP:
   Menu → PHP → php.ini (или через панель модулей).
2. Добавьте или обновите секцию [xdebug] следующими параметрами:

zend_extension = xdebug

[xdebug]
xdebug.mode = debug,develop
xdebug.start_with_request = yes     ; запуск отладки при запросе
xdebug.client_host = 127.0.0.1       ; адрес IDE
xdebug.client_port = 9003            ; порт по умолчанию для Xdebug 3
xdebug.log_level = 0                 ; можно включить логирование
xdebug.output_dir = "%sprogdir%/userdata/temp/xdebug"

📝 В отличие от старых версий Xdebug 2, Xdebug 3 изменил синтаксис и значения параметров (mode, start_with_request). Обязательно используйте именно новую конфигурацию. ([JetBrains][1])

3. Сохраните файл и перезапустите Open Server.

---

🧠 2. Проверка установки Xdebug

Чтобы убедиться, что Xdebug активен:

1. Создайте файл phpinfo.php в корне вашего проекта:

<?php
phpinfo();

2. Откройте его в браузере через локальный домен (http://localhost/phpinfo.php).
3. В выводе найдите секцию Xdebug — Version (это подтверждает, что расширение загружено).

---

🛠️ 3. Настройка PhpStorm для отладки

Конфигурация интерпретатора

1. Откройте Settings/Preferences (Ctrl+Alt+S)
2. Перейдите в Languages & Frameworks → PHP
3. Убедитесь, что выбран правильный PHP-интерпретатор (тот же, что используется Open Server).

PhpStorm автоматически покажет версию PHP и наличие Xdebug. Если Xdebug не виден — пересмотрите конфигурацию php.ini.

---

📡 Включение отладчика и порт

Перейдите в:

Languages & Frameworks → PHP → Debug

✔ Установите Debug Port: 9003
✔ Включите Can accept external connections (PhpStorm будет слушать входящие подключения от Xdebug)

---

🗺️ Настройка сервера в PhpStorm

Чтобы Xdebug правильно сопоставлял пути файлов:

1. Languages & Frameworks → PHP → Servers
2. Нажмите + и добавьте сервер:
   • Name: любое удобное имя (например, OpenServer).
   • Host: доменное имя проекта (localhost или ваш виртуальный хост).
   • Port: 80 или 443 (в зависимости от протокола).
   • Debugger: Xdebug
   • Поставьте галочку Use path mappings
3. Укажите локальные пути проекта и путь на сервере (обычно совпадают для локальной среды).

Это важно — без корректного сопоставления PhpStorm не сможет остановиться на брейкпойнтах.

---

🪲 4. Запуск отладки

1. В PhpStorm включите Start Listening for PHP Debug Connections (значок жука в панели).
2. Поставьте брейкпойнт (клик рядом с номером строки).
3. Откройте страницу в браузере.
4. При старте сессии отладки PhpStorm предложит принять соединение — подтвердите.
5. Скрипт остановится на брейкпойнте — теперь вы можете шагать по коду, смотреть переменные, стек вызовов и др.

---

🔍 5. Отладка браузером (по желанию)

Чтобы запускать отладку через браузер удобно, можно использовать расширение Xdebug helper для Chrome или аналогичное для Firefox. Это позволяет включать/выключать сессию Xdebug одной кнопкой.

---

📊 6. Профилирование и анализ

Xdebug также умеет профилировать выполнение скриптов (сбор данных о времени и памяти). Для этого:

1. В php.ini добавьте:

xdebug.mode = debug,develop,profile

2. После перезапуска Open Server в каталоге xdebug.output_dir появятся файлы профилировщика.
3. Откройте их в QCacheGrind/KCacheGrind или других анализаторах профиля PHP.

---

⚠️ Частые проблемы и решения

🔹 PhpStorm не останавливает на брейкпойнте
Проверьте:
✔ корректный порт (9003)
✔ включен слушатель в IDE
✔ настроены правильные серверы и маппинги

🔹 Xdebug не запускается по запросу
Попробуйте установить:

xdebug.start_with_request = trigger

и указать триггер в браузере (XDEBUG_SESSION=PHPSTORM).

🔹 Конфликты портов или блокировка фаерволом
Иногда стандартные порты заняты системой или блокируются. В этом случае можно выбрать другой порт в xdebug.client_port и в PhpStorm.

---

🧠 Заключение

Правильная настройка Xdebug с Open Server и PhpStorm помогает:

✔ существенно ускорить разработку
✔ быстро находить и исправлять ошибки
✔ анализировать поведение кода до мельчайших подробностей

Эта инструкция актуальна для последних версий Xdebug (3.x) и PhpStorm (2025+), и использует современные принципы конфигурации и отладки в локальной среде.