1. Публикации
  2. Как настроить отладчик Xdebug в PhpStorm для проекта, работающего в VirtualBox

Как настроить отладчик Xdebug в PhpStorm для проекта, работающего в VirtualBox

Настройка отладчика в PhpStorm для проекта, работающего в VirtualBox (в данном случае мы используем Vagrant и Homestead в Windows 11 для проекта Laravel), включает настройку как серверной, так и клиентской стороны (PhpStorm) для отладки. В основном этот процесс включает в себя настройку Xdebug на вашей виртуальной машине, а затем настройку PhpStorm для связи с ним.

Вот пошаговые инструкции:

Установка  и настройка Xdebug на сервере VirtualBox (Homestead)

  1. SSH в ваш Vagrant:
    vagrant ssh
  2. Установите Xdebug:
    sudo apt-get install php-xdebug
  3. Обновите конфигурацию Xdebug. Откройте файл конфигурации Xdebug в редакторе, например `nano`:
    sudo nano /etc/php/8.1/mods-available/xdebug.ini

    Затем добавьте или измените описанную конфигурацию:
    zend_extension=xdebug.so
    xdebug.mode=debug
    xdebug.discover_client_host = true
    xdebug.start_with_request=yes
    xdebug.log=/var/log/xdebug.log

    Путь к этому файлу может отличаться в зависимости от конфигурации вашего сервера и версии PHP. 
    Чтобы найти файл конфигурации Xdebug, вам необходимо:
    sudo find /etc/php -name '*xdebug*'
    Эта команда должна вывести список всех файлов и каталогов, содержащих слово «xdebug» внутри `/etc/php`. Найдите в результатах файл `.ini`. Если вы его видите, скорее всего, это ваш файл конфигурации Xdebug. Обратите внимание на его путь.
    Если вы не видите ни одного файла `.ini` для Xdebug, возможно, он неправильно установлен или связан. В таком случае вам может потребоваться переустановить Xdebug или убедиться, что он включен.
    Для типичной настройки веб-разработки с Vagrant и Homestead с использованием nginx или Apache вы, скорее всего, используете PHP-FPM. Поэтому вам следует изменить файл, связанный с FPM:
    /etc/php/8.1/fpm/conf.d/20-xdebug.ini
    Однако имейте в виду, что если этот 20-xdebug.ini является символической ссылкой на /etc/php/8.1/mods-available/xdebug.ini (что весьма вероятно), то обновление любого из них повлияет на все контексты (CGI, PHPDBG и FPM). Таким образом, если вы измените файл mods-available/xdebug.ini, это изменит настройки для всех остальных, при условии, что они являются символическими ссылками.
    Чтобы определить, является ли файл символической ссылкой, вы можете использовать Команда ls с опцией -l:
    ls -l /etc/php/8.1/fpm/conf.d/20-xdebug.ini
  4. Перезапустите службу PHP:
    sudo service --status-all | grep php | awk '{print $4}' | xargs -I {} sudo service {} restart

Настроить PhpStorm

  1. Откройте PhpStorm.
  2. Перейдите в «Файл» > `Настройки` (или `PhpStorm` > `Настройки` в macOS).
  3. Выберите PHP.
  4. Нажмите кнопку `...` рядом с интерпретатором CLI. Здесь вы можете настроить удаленного переводчика, если вы еще этого не сделали. Это гарантирует, что PhpStorm будет знать об исполняемом файле PHP и конфигурации внутри поля Vagrant.
  5. Все еще в настройках выберите `PHP` > `Серверы`.
  6. Нажмите кнопку `+`, чтобы добавить новый сервер:
    • Имя: любое имя, например `MyProject`
    • Хост: `myproject.test`
    • Порт: `80`
    • Отладчик: `Xdebug`
    • Использовать сопоставления путей:
    • Сопоставьте каталог на вашем локальном компьютере с каталогом в вашем поле Vagrant.
      Например, если ваш проект находится в `c:\dev\my_project` на вашем хост-компьютере и в `/home/vagrant/code/my_project` в поле Vagrant установите это сопоставление.

  7. Выберите `PHP` > `Debug`
    Убедитесь, что для `Debug port` установлено значение `9003` (или любой другой порт, который вы установили в конфигурации Xdebug).
  8. Нажмите «Применить», а затем «ОК».

Начало сеанса отладки

  1. Установите точку останова в PhpStorm, щелкнув поле рядом со строкой кода.
  2. Убедитесь, что в правом верхнем углу PhpStorm активен значок телефона (прослушивание отладочных соединений) (он должен быть зеленым).
  3. В браузере перейдите к веб-приложению, которое вы используете в своем ящике Vagrant.
  4. Если все настроено правильно, то при нажатии на строку с точкой останова PhpStorm должен выделить эту строку и позволить вам проверять переменные, пошагово выполнять код и т. д.
  5. Удачной отладки!

Помните, что иногда конфигурации или пути могут незначительно отличаться в зависимости от используемой вами версии программного обеспечения, поэтому всегда обращайтесь к документации, если у вас возникнут какие-либо проблемы.

Профилирование с Xdebug

Xdebug представляет собой мощный инструмент для отладки и профилирования PHP-кода. Чтобы измерить время выполнения блока кода с его помощью, активируйте функцию профилирования, добавив или модифицировав следующие настройки в файле 20-xdebug.ini:

xdebug.mode = profile
xdebug.start_with_request = trigger
xdebug.output_dir = /home/vagrant/code

В указанной последней строке путь ведёт к общей папке проектов на виртуальной машине, что позволяет немедленно получить доступ к файлам профилирования из Windows.

Активация профилирования

Для запуска профилирования, запросите страницу, передав параметр XDEBUG_PROFILE. Например: http://yourdomain.com/yourscript.php?XDEBUG_PROFILE=1. При этом Xdebug создаст файл профилирования.

Для профилирования конкретного блока кода используйте функции xdebug_start_profiling() и xdebug_stop_profiling() на начале и конце блока соответственно.

Анализ результатов

После завершения выполнения кода в заданной директории (xdebug.output_dir) появится файл профилирования с расширением .cachegrind. Для его анализа без PhpStorm рекомендуется использовать KCacheGrind (Linux) или QCacheGrind (Windows, macOS). Внутри этих программ вы сможете анализировать время выполнения каждой функции.

В PhpStorm данный файл можно открыть через "Tools" > "Analyze Xdebug Profiler Snapshot". После загрузки файла профилирования в PhpStorm будет предоставлена детализированная информация о времени и памяти, затраченной на выполнение каждой функции.

На основе полученных данных вы сможете определить узкие места в коде и произвести необходимую оптимизацию.

Помните: профилирование может замедлить ваш код, поэтому не используйте его постоянно на продакшн-сервере или в обычном режиме работы приложения.

Решение проблем с Xdebug

Часто бывает так, что, следуя проверенной инструкции, вы не получаете ожидаемого результата. Причин может быть множество, и, к сожалению, не все из них легко учесть. Ниже приведены типичные проблемы и способы их решения в контексте использования Xdebug:

  • Xdebug установлен, но не активен на сервере: Если команда php -m | grep xdebug не возвращает результат, убедитесь, что вы настроили Xdebug для нужной версии PHP. Напоминаю, что разные проекты могут использовать разные версии PHP, и потребуется настроить Xdebug для каждой из них.
  • Использование функции xdebug_info(): Если вы столкнулись с проблемами, попробуйте вызвать PHP-функцию xdebug_info(). Она покажет актуальную информацию о настройках Xdebug и поможет убедиться в их корректности.
  • Xdebug активен, но phpStorm не реагирует: Если Xdebug работает на сервере, но phpStorm не получает сигналов, возможная причина может крыться в вашем брандмауэре или файрволе. Проверьте правила входящих и исходящих соединений. В моем случае проблема заключалась именно в этом: сначала всё работало корректно, но позже связь внезапно прервалась.
  • Режим профилирования: Если Xdebug настроен в режиме профилирования, обратите внимание, что отладка кода при этом не будет производиться.

Помните, что инструменты и системы постоянно развиваются, поэтому при возникновении проблем всегда стоит обращаться к актуальной документации и сообществу разработчиков.