Как установить xdebug php
Installation
This section describes on how to install Xdebug.
Installing on Linux #
Xdebug’s latest version is 3.1.2.
Linux distributions might be providing an old and/or outdated version. If the package manager installs a version that is no longer supported (see Supported Versions), please install Xdebug with PECL, or from source instead.
Installing with PECL #
You can install Xdebug through PECL on Linux & macOS with Homebrew. Run:
On Apple M1 hardware, you might instead need to use:
You should ignore any prompts to add «extension=xdebug.so» to php.ini — this will cause problems.
If pecl did not add the right line, skip to the Configure PHP section.
1 On macOS, you should have PHP installed with Homebrew.
Installing on Windows #
There are a few precompiled modules for Windows, they are all for the non-debug version of PHP. You can get those at the download page. Follow these instructions to get Xdebug installed.
Installation From Source #
Obtain #
You can download the source of the latest stable release 3.1.2.
Alternatively you can obtain Xdebug from GIT:
This will checkout the latest development version which is currently 3.2.0dev. This development branch might not always work as expected, and may have bugs.
You can also browse the source on GitHub at https://github.com/xdebug/xdebug.
Compile #
There is a wizard available that provides you with the correct file to download, and which paths to use.
Debian users can do that with:
And RedHat and Fedora users with:
Unpack the tarball:
You should not unpack the tarball inside the PHP source code tree. Xdebug is compiled separately, all by itself, as stated above.
If phpize is not in your path, please make sure that it is by expanding the PATH environment variable. Make sure you use the phpize that belongs to the PHP version that you want to use Xdebug with. See this FAQ entry if you’re having some issues with finding which phpize to use.
Configure PHP #
Find out which PHP ini file to modify.
Run a script with the following to find all configuration files that PHP has loaded:
If that file does not exist, but there are other files in a conf.d or similar directory, you can create a new file there too. Please name it 99-xdebug.ini in that case.
There could be more than one php.ini file. In many set-ups there is a different one for the command line (often cli/php.ini ) and the web server (often fpm/php.ini ).
If you want to use Xdebug and OPCache together, you must have the zend_extension line for Xdebug below the line for OPCache, or in a file starting with a higher number (ie. 99-xdebug.ini vs 20-opcache.ini ), otherwise they won’t work properly together.
Add the following line to this PHP ini file:
Restart your webserver, or PHP-FPM, depending on what you are using.
Verify that Xdebug is now loaded.
Create a PHP page that calls xdebug_info(). If you request the page through the browser, it should show you an overview of Xdebug’s settings and log messages.
On Windows, you should place the php_xdebug.dll in the ext/ directory, which is a child directory in your PHP installation tree.
If you have trouble with this, please refer to the installation wizard to help you guide through this process.
With Xdebug loaded, you can now enable individual features, such as Step Debugging, or Profiling.
Related Content #
This video teaches you how to troubleshoot your Xdebug setup. It explains how to find out how Xdebug is configured, which settings have been made, and what it is attempting to do regarding its different features.
This video introduces Xdebug 3’s modes — the new way to configure which parts of Xdebug you have enabled.
Related Settings and Functions #
Settings #
string xdebug.log = #
Configures Xdebug’s log file.
Xdebug will log to this file all file creations issues, Step Debugging connection attempts, failures, and debug communication.
Enable this functionality by setting the value to a absolute path. Make sure that the system user that PHP runs at (such as www-data if you are running with Apache) can create and write to the file.
The file is opened in append-mode, and will therefore not be overwritten by default. There is no concurrency protection available.
The log file will include any attempt that Xdebug makes to connect to an IDE:
It includes the opening time ( 2020-09-02 07:19:09.616195 ), the IP/Hostname and port Xdebug is trying to connect to ( localhost:9003 ), and whether it succeeded ( Connected to client ). The number in brackets ( [2693358] ) is the Process ID.
It includes: [2693358] process ID in brackets 2020-09-02 07:19:09.616195 opening time
All warnings and errors are described on the Description of errors page, with detailed instructions on how to resolve the problem, if possible. All errors are always logged through PHP’s internal logging mechanism (configured with error_log in php.ini ). All warnings and errors also show up in the diagnostics log that you can view by calling xdebug_info().
Step Debugger Communication
The debugging log can also log the communication between Xdebug and an IDE. This communication is in XML, and starts with the XML element:
The fileuri attribute lists the entry point of your application, which can be useful to compare to breakpoint_set commands to see if path mappings are set-up correctly.
Beyond the element, you will find the configuration of features:
The xdebug.log_level setting controls how much information is logged.
Many Linux distributions now use systemd, which implements private tmp directories. This means that when PHP is run through a web server or as PHP-FPM, the /tmp directory is prefixed with something akin to:
This setting can additionally be configured through the XDEBUG_CONFIG environment variable.
integer xdebug.log_level = 7 #
Configures which logging messages should be added to the log file.
The log file is configured with the xdebug.log setting.
The following levels are supported:
| Level | Name | Example |
|---|---|---|
| 0 | Criticals | Errors in the configuration |
| 1 | Errors | Connection errors |
| 3 | Warnings | Connection warnings |
| 5 | Communication | Protocol messages |
| 7 | Information | Information while connecting |
| 10 | Debug | Breakpoint resolving information |
Criticals, errors, and warnings always show up in the diagnostics log that you can view by calling xdebug_info().
Criticals and errors are additionally logged through PHP’s internal logging mechanism (configured with error_log in php.ini ).
This setting can additionally be configured through the XDEBUG_CONFIG environment variable.
string xdebug.mode = develop #
This setting controls which Xdebug features are enabled.
The following values are accepted:
off Nothing is enabled. Xdebug does no work besides checking whether functionality is enabled. Use this setting if you want close to 0 overhead. develop Enables Development Helpers including the overloaded var_dump(). coverage Enables Code Coverage Analysis to generate code coverage reports, mainly in combination with PHPUnit. debug Enables Step Debugging. This can be used to step through your code while it is running, and analyse values of variables. gcstats Enables Garbage Collection Statistics to collect statistics about PHP’s Garbage Collection Mechanism. profile Enables Profiling, with which you can analyse performance bottlenecks with tools like KCacheGrind. trace Enables the Function Trace feature, which allows you record every function call, including arguments, variable assignment, and return value that is made during a request to a file.
XDEBUG_MODE environment variable
You can also set Xdebug’s mode by setting the XDEBUG_MODE environment variable on the command-line; this will take precedence over the xdebug.mode setting, but will not change the value of the xdebug.mode setting.
Some web servers have a configuration option to prevent environment variables from being propagated to PHP and Xdebug.
Make sure that your web server does not clean the environment, or specifically allows the XDEBUG_MODE environment variable to be passed on.
Functions #
Show and retrieve diagnostic information
This function presents APIs to retrieve information about Xdebug itself. Which information gets returned, or displayed, depends on which arguments, or none at all, are given.
$category =
Without arguments, this function returns an HTML page which shows diagnostic information. It is analogous to PHP’s phpinfo() function.
The HTML output includes which mode is active, what the settings are, and diagnostic information in case there are problems with debugging connections, opening of files, etc.
Each warning and error in the diagnostics log also links through to the Description of errors documentation page.
$category = ‘mode’ (New in Xdebug 3.1)
The function returns an array of all the enabled modes, whether through xdebug.mode or the XDEBUG_MODE environment variable.
Example:
Returns:
$category = ‘extension-flags’ (New in Xdebug 3.1)
The only flag that is available, is the compression flag. If this flag is enabled, then the xdebug.use_compression setting is available, and enabled by default.
Profiling and Function Trace will create GZip compressed files if the xdebug.use_compression setting is turned on (the default).
Example:
Returns:
This site and all of its contents are Copyright © 2002-2021 by Derick Rethans.
All rights reserved.
Установка и настройка Xdebug
Есть очень хороший инструмент для отладки php кода — Xdebug. Сегодня я расскажу как его развернуть на своей машине, а также как настроить NetBeans IDE на работу с ним.
Немного о Xdebug
Основной целью расширения является максимально возможное упрощение отладки PHP-скриптов и добавление в разработку на PHP таких удобств, как точки останова, пошаговое выполнение и наблюдение за выражениями, которое мы привыкли видеть только в компилируемых языках программирования.
Помимо этого, расширение позволяет выполнять профилировку приложения и находить те части, которые замедляют его работу. Поддерживается также выполнение произвольного кода на точке останова. Xdebug стилизирует вывод ошибок, благодаря чему, читать ошибки становится гораздо удобнее. Кроме того, есть возможность самому указать, что будет выводиться при ошибке. На этом список возможностей не заканчивается, уж поверьте, у Xdebug также есть ряд других полезных при отладке функций.
В целом, расширение нужно, в первую очередь, для экономии времени разработчиков, так как позволяет быстрее локализовать ошибку в коде.
Установка Xdebug
Уже довольно давно Xdebug, как расширение для php, присутствует в репозиториях. Поэтому его установка очень проста, для этого введите в консоли следующую команду.
Настройка Xdebug
Настройка расширения выполняется при помощи редактирования конфигурационных ini файлов. Тут есть два пути:
1. В php.ini создаем секцию [xdebug] и в ней задаем параметры.
2. Все параметры задаем в xdebug.ini, который хранится тут /etc/php5/conf.d/xdebug.ini
Тут решать Вам и только Вам.
Куда писать — определились. Определимся что писать?
Давайте я приведу список настроек, и поясню, что они означают:
[php] [xdebug] xdebug.default_enable = On; включить xdebug по умолчанию
xdebug.var_display_max_depth = 6; глубина показа дампа массивов и объектов
xdebug.remote_enable = On; включить удаленную отладку
xdebug.remote_host = 127.0.0.1; хост для удаленной отладки
xdebug.remote_port = 9000; порт для удаленной отладки
xdebug.remote_handler = dbgp; протокол для отладки
xdebug.idekey = netbeans-xdebug; идентификатор, который будет отправлять наша IDE
xdebug.remote_autostart = 1; автоматический запуск отладки
xdebug.remote_log=/tmp/xdebug/xdebug.log; лог-файл для удаленной отладки
xdebug.profiler_enable_trigger = 1; запускать профилирование по триггеру
xdebug.profiler_enable = 0; включить профилирование
xdebug.profiler_output_dir = /tmp/xdebug/profiler/; директория для хранения результатов профилирования
xdebug.show_local_vars = 1; отобразить все локальные переменные в случае возникновения ошибки
xdebug.overload_var_dump = 1; включает усовершенcтвованный var_dump
[/php]
После, необходимо чтобы наши изменения подтянулись.
Для этого нужно перезагрузить apache или php-fpm (в зависимости от того, что Вы используете).
Чтобы убедиться, что все хорошо, выведите
phpinfo();
Если такой текст имеется — значит все отлично:
This program makes use of the Zend Scripting Language Engine:
Zend Engine v2.3.0, Copyright (c) 1998-2012 Zend Technologies
with Xdebug v2.1.0, Copyright (c) 2002-2010, by Derick Rethans
Вы должны увидеть красивый стилизированный вывод содержимого массива.
Теперь создадим ошибку (забудем ; в конце строки)
[php] echo ‘Xdebug’
[/php]
Вы должны увидеть подробное сообщение об ошибке, представляющее собой таблицу.
Настройка PhpStorm
Настройка NetBeans IDE
Остальные параметры настраиваем под себя.
Ну, а о том, как выполнять отладку — в другой раз.
Отладка php в Visual Studio Code (Xdebug, Windows)
В некоторых случаях может возникнуть необходимость отладки приложений на php. Visual Studio code предоставляет такую возможность при условии установки дополнительного расширения PHP Debug (marketplace, github).
Установка PHP Debug
Установка и настройка Xdebug
PHP Debug использует для отладки Xdebug. Для настройки Xdebug пройдите по ссылке. Предполагается, что на локальной машине уже установлен и настроен сервер apache. Здесь и далее действия указаны для Windows. Можно создать файл, например, test.php содержащий:
Открыть его в браузере и скопировать содержимое страницы в диалоговое окно. Другой способ:
Кроме этого, добавьте нижеследующие строки. Итоговое добавление будет примерно таким:
Как вы уже, возможно догадались, в данном примере на локальной машине установлен XAMPP.
Примечание: С версией Xdebug 2.5 и выше Visual Studio code не работает. Поэтому выбирайте соответствующий вашей версии php файл *.dll.
Настройка Visual Studio code
Вызовите панель отладки (1) и нажмите на иконку с маленькой шестеренкой (2).
Настройка PHP Debug на этом окончена.
Отладка php в Visual Studio code
Откройте в браузере ваше приложение\сайт. Откройте папку с приложением в Visual Studio code. Установите в нужных файлах и строках точки остановки. Откройте панель отладки и выберите для запуска отладки команду Listen for Xdebug (1). Нажмите кнопку запуска (2).
Обновите страницу в браузере и наслаждайтесь.
Xdebug через Windows Subsystem For Linux 2 (WSL2)
Под катом небольшая заметка про то как можно настроить удобное окружение для работы с PHP, xdebug через Windows Subsystem For Linux 2 (WSL 2).
Для начала немного истории
Я очень долгое время жил в мире Ubuntu — писать на PHP, NodeJS, GoLang сразу на той же системе, на которой все будет запускаться, крайне приятно. Но, к сожалению, наличие руководящей должности приводит к тому, что приходится пользоваться большим количеством софта, который работает только на Windows.
Очень долгое время я просто жил «через SSH». На моем ноутбуке просто стоял PhpStorm, в котором я через ssh правил файлы на Ubuntu сервере — просто и работает.
Виртуалки сразу отбросил — ноут не очень радовался соседям внутри:) Докер поджирал заметно ресурсы и без того перегруженного 100500 вкладками и копиями запущенных Phpstorm небольшой ноутбук dell e7390:) Докер крутится у нас в бою и как раз на дев серверах, куда я хожу через sftp.
Но прошло время и стало возможным легко и просто запустить у себя на винде WSL2 (http://habr.com/ru/news/t/516054) и я решил все же сделать удобное окружение для своей работы.
Теперь к делу
Базовая установка системы
Как установить WSL на Windows есть множество инструкций. Я все сделал по официальному мануалу с сайта Microsoft
После успешной установки в PowerShell нужно написать команду wsl и мы погружаемся внутрь Linux, который внутри Windows
Далее идет череда стандартных команд для настройки веб сервера на Ubuntu:
Теория гласит (да и здравый смысл тоже), что файлы, с которыми оперирует php должны быть в самой системе Linux, а не в виде подмонтированного NTFS винды. Если нужно чтобы файлы были полностью нативно в системе можно сделать следующее.
Но в данном способе есть один неприятный минус — надо синхронизировать файлы. Например вы перешли на другую ветку в винде = надо в линуксе тоже переходить в эту ветку. Двойная работа. Подумываю над каким нибудь хитрым скриптом, который с rsync будет все это делать сам, но пока не придумал. Если придумаете, пишите — буду очень благодарен:)
Также не забывайте настройку Apache, чтобы он ходил в нужные директории. Если что, конечно, можно сделать связку из php-fpm и nginx — тут уже на ваш вкус.
Настройка xdebug на сервере
Далее настраиваем xdebug стандартным путем по любому мануалу из интернета. Я опишу кратко порядок действий.
Устанавливаем xdebug через sudo apt-get install php-xdebug
Открываем sudo nano /etc/php/7.2/mods-available/xdebug.ini и приводим к такому содержимому
Перезапускаем apache sudo service apache2 restart
Костыль для обратной связи
В поисках решения этой проблемы я наткнулся на пост в интернете, откуда решил взять gif-ку что наглядности.
Небольшая гифка-пояснение
Автор поста предлагает свой github репозиторий с C# приложением, которое надо добавить в планировщик Windows чтобы команда выполнялась при каждом запуске ПК. У меня сходу этот скрипт не сработал, да и проводить какие-то кастомизации в Windows не хотелось.
Ценой нескольких часов я собрал «костыльный» bash скрипт, который прописывает автоматически IP адрес хостовой системы в /etc/hosts внутри linux при каждом входе в WSL — инструкцию и скрипт выложил на github.
Но этот скрипт нужно запускать при первом запуске системы. Руками такое делать «не красиво», а стандартный systemd и rc.local через wsl не работают. Поэтому пришлось использовать костыльное и небезопасное, но рабочее решение.
При каждом входе в wsl запускается скрипт, который прописывает все что нужно в /etc/hosts и по адресу wsl.host наш linux будет видеть windows. Если кто-то знает как это можно достичь более правильным путем, буду благодарен если отпишите способ в комментариях или можно лично.
После входа в wsl стоит проверить, что хост прописался — пишем команду cat /etc/hosts и на последнем месте должно быть что-то вроде этого:
172.26.64.1 wsl.host
Настройка xdebug в PhpStorm на Windows
После завершения всех работ внутри WSL можно перейти к настройке дебаггера в PhpStorm
File->Settings->Languages & Framework->PHP
Открываем выбор интерпретаторов
Первый вариант «From Docker, Vagrant, VM, WSL, Remote»
Выбираем установленный WSL
Убеждаемся, что xdebug активирован
File->Settings->Languages & Framework->PHP->Debug
Активируем прослушивание дебаггера и указываем порт, который ранее указали в WSL (у меня это 9002, а изначально он 9000)
В итоге должно выглядеть примерно так
Убираем галочку в advanced напротив пункта «Pass required configuration options..»
Если ее не снять, то дебаггер будет передавать свои параметры по умолчанию и они будут перезатираться — в итоге наш wsl.host будет заменен на 127.0.0.1 и ничего работать не будет.
Причем эта проблема проявляется только при отладке через консоль, т.к. при отладке HTTP сервера никакие конфиги не пробрасываются и забираются из ini файлов.
На этом все — можно проверять работает ли дебаггер.
Проверка результата
Добавляем конфигурацию Php Script
Указываем путь до скрипта и нужные аргументы
Сохраняем, закрываем и запускаем дебаггер
Вместо заключения
Таким образом, перелопатив несколько разных источников, статей, гистов я пришел к «почти идеальному» рабочему окружению при работе с PHP. Если есть где чего можно улучшить/доработать пишите в комментарии или в любой другой способ связи со мной.
Xdebug? Отладка по-взрослому. И почему ты должен его использовать
XDEЧТО?
Xdebug полностью исключает необходимость в использовании monkey-дебага, типа:
Почему это удобнее?
Во-первых, breakpoint-ы, ставить проще и быстрее.
Во-вторых, такой структурированной и полной информации не добиться ни от какой из существующих debug-функций.
А в-третьих, используя это расширение, можно менять значения любых переменных налету, изучая влияние новых значений на приложение в целом.
Поддержка в IDE и текстовом редакторе
Большинство современных IDE без проблем поддерживают xdebug. Настройка индивидуальна, в зависимости от выбранной IDE (возможно, потребуется дополнительная установка плагинов). Например, в SublimeText, Netbeans, или даже в Notepad++ предоставляются возможности по использованию дебаггера.
Моя любимая IDE уже имеет встроенную поддержку xdebug-а. Потому, настройка здесь ещё проще, чем хотелось бы.
По правде говоря, лучше IDE, чем PhpStorm, я пока не встречал, и именно про такие программы говорят: «она стоит каждого своего цента». Потому, я советую в разработке использовать именно её. Потому, все скриншоты будут исключительно из PhpStorm-а.
Установка XDEBUG
Установка в разных операционных системах отличается. Я же использую windows, openserver. Потому, продемонстрирую пошаговую инструкцию установки xdebug на openserver.
Заходим в php.ini 
Находим меню [Xdebug] 
В котором, ищем, и устанавливаем параметры (в основном они закомментированы, потому, нужно раскомментировать их, удалив в начале ; ):
Сохранив изменения, перезагрузив сервер, и вызвав phpinfo() можно убедиться, что xdebug появился, и стал доступным с указанными ранее параметрами. 
Теперь, из серверных настроек всё котово. Осталось сделать так, чтобы можно было вызвать дебаггер из браузера. Ранее всё было сложнее, однако, сейчас всё сводится к установке одного расширения google chrome Xdebug helper.
Настройка PHPSTORM
И, аналогично, в File | Settings | Languages & Frameworks | PHP | Debug | DBGp Proxy нужно указать IDE KEY, и порт: 
Первый breakpoint
Теперь осталось написать код, и поставить в нём точку остановки. Сделать это просто: достаточно, напротив строки, на которой предполагается остановка, нажать на пустом месте, расположенном скраю. 
И, если всё было настроено правильно, то, открыв текущий проект в браузере, увидим постоянно загружающуюся страницу. А в IDE, одновременно с этим, откроется окно, со всеми доступными параметрами отладки. Вот так и выглядит xdebug панель отладки в PhpStorm: 
Детальный разбор debug-панели
Рассмотрим отладку на примере исходного кода:
Панель имеет несколько функциональных кнопок управления процессом отладки 
Если поставить breakpoint в цикле, то остановка будет срабатывать на каждой его итерации, а не один раз за весь цикл
Отладка чужих проектов
Перед тем, как закончить этот туториал, я хотел бы описать одну очень распространённую проблему при выполнении проектов.
Есть много проектов, которые написаны в виде одного большого полотна кода. Понять логику которого очень сложно. Потому, единственным правильным решением будет вызов xdebug-а с первой строки, и осуществление навигации с помощью рассмотренных выше функций (F8, или F7), построчно изучая логику работы приложения.
Поверьте, но продвинутое знание xdebug-а очень сильно упрощает жизнь программиста
Резюме
Сегодня вы изучили, что такое xdebug, как установить xdebug на open server, и как работать с xdebug в PhpStorm.
Subscribe to Блог php программиста: статьи по PHP, JavaScript, MySql
Get the latest posts delivered right to your inbox