Отладка PHP: var_dump, Xdebug и PhpStorm
Если нужно узнать тип и значение переменной, начните с var_dump. Если важно понять, где значение изменилось и почему код пошёл по другой ветке, поставьте точку останова в Xdebug. Ниже показано, как пользоваться обоими способами в PHP 8.3–8.5 и подключить отладчик к PhpStorm или VS Code.
Быстрая отладка PHP через var_dump()
var_dump() выводит тип и значение. Для строк он показывает длину в байтах, для массивов раскрывает ключи и элементы. Это помогает, когда данные из формы, JSON или базы выглядят одинаково при обычном выводе, но по-разному ведут себя при сравнении и передаче в типизированные функции.
<?php
declare(strict_types=1);
$input = ['quantity' => '0', 'discount' => null];
// Строка '0' отличается от целого числа 0.
var_dump($input['quantity'], $input['quantity'] === 0);
// Ключ существует, хотя его значение равно null.
var_dump(isset($input['discount']), array_key_exists('discount', $input));Первая проверка покажет string(1) "0" и bool(false). Вторая покажет bool(false) и bool(true). Для типизированной обработки входных данных сначала проверьте значение на границе приложения, затем передайте его дальше в нужном типе. declare(strict_types=1) не преобразует значения внутри массива и не меняет правила сравнения.
print_r($value, true)возвращает представление массива или объекта как строку. Для диагностики типов удобнееvar_dump().var_export($value, true)возвращает PHP-представление значения. Его удобно использовать для небольших массивов, которые нужно перенести в тест.error_log()отправляет диагностическое сообщение в настроенный журнал. В JSON API это позволяет сохранить тело ответа пригодным для разбора.
Если var_dump() перед отправкой заголовков приводит к headers already sent или ломает JSON, перенесите диагностику в журнал либо поставьте точку останова. Для журнала выбирайте конкретные поля, например идентификатор запроса и тип значения через get_debug_type(). Дампы целых запросов и объектов могут содержать пароли, токены и персональные данные.
Ошибки, исключения и различия PHP 8.3–8.5
В локальном окружении включите error_reporting = E_ALL, display_errors = On и log_errors = On. На рабочем сервере оставьте регистрацию ошибок и установите display_errors = Off. Если файл не разбирается из-за синтаксической ошибки, вызов ini_set() внутри него не выполнится. Проверьте конфигурацию среды и запустите php -l тем интерпретатором, которым исполняется код.
<?php
declare(strict_types=1);
function decodeQuantity(string $json): int
{
$data = json_decode($json, true, flags: JSON_THROW_ON_ERROR);
$quantity = is_array($data) ? ($data['quantity'] ?? null) : null;
// Проверяем тип и диапазон до передачи значения дальше.
if (!is_int($quantity) || $quantity < 1) {
throw new InvalidArgumentException('Ожидается целое quantity больше нуля');
}
return $quantity;
}
foreach (['{"quantity":2}', '{"quantity":"2"}', '{'] as $payload) {
try {
var_dump(decodeQuantity($payload));
} catch (JsonException | InvalidArgumentException $e) {
error_log($e->getMessage());
}
}На корректном JSON функция вернёт int(2). Строковое число вызовет InvalidArgumentException, а обрезанный JSON — JsonException. С точки останова на исключении можно увидеть исходное состояние до того, как обработчик запишет сообщение.
| Версия | Что учитывать при отладке |
|---|---|
| PHP 8.3 | Появилась json_validate() для проверки синтаксиса JSON. Если данные всё равно нужно декодировать, достаточно одного вызова json_decode() с JSON_THROW_ON_ERROR. |
| PHP 8.4 | Неявно допускающие null параметры вроде string $name = null помечены устаревшими. Объявите тип явно, например ?string $name = null. При отладке свойств учитывайте хуки get и set. Доступ к свойству может выполнять пользовательский код. |
| PHP 8.5 | Встроенный FatalError предоставляет программе сведения о фатальной ошибке через обработчик завершения. Для обычных TypeError и исключений по-прежнему начинайте со стека вызовов и точки останова на исключении. |
Если ошибка воспроизводится только на одной из этих версий, запустите минимальный пример под той же минорной версией, с теми же расширениями и настройками. Интерпретатор, выбранный в IDE, может отличаться от интерпретатора в терминале или веб-контейнере.
Xdebug для PHP: установка и первый сеанс
Для пошаговой отладки нужен Xdebug 3, совместимый с конкретной версией PHP и способом её сборки. Устанавливайте расширение в среду, где исполняется скрипт. Проверьте CLI с помощью php -v, php --ri xdebug и php --ini. Веб-сервер может использовать другой набор INI-файлов. В локальной веб-среде это можно выяснить через php_ini_loaded_file(), php_ini_scanned_files() и extension_loaded('xdebug').
; Если пакет уже загрузил расширение, пропустите эту строку.
zend_extension=xdebug
; Запускаем пошаговую отладку по запросу.
xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.client_host=127.0.0.1
xdebug.client_port=9003Строка zend_extension предполагает, что PHP может найти расширение по имени. При ручной установке укажите путь к установленному файлу расширения. После изменения конфигурации перезапустите PHP-FPM или другой долгоживущий PHP-процесс. CLI прочитает настройки при следующем запуске.
Включите прослушивание в IDE и поставьте точку на строке var_dump() в первом примере. Сохраните его как debug-demo.php и запустите из каталога с файлом. Команда ниже рассчитана на Bash-совместимую оболочку.
# Запускаем только этот процесс с триггером Xdebug.
XDEBUG_TRIGGER=1 php debug-demo.phpДля веб-запроса передайте параметр запроса или cookie XDEBUG_TRIGGER. Если задан xdebug.trigger_value, его значение должно совпасть со значением триггера. Xdebug сам подключается из PHP к IDE. Поэтому адрес 127.0.0.1 подходит, когда IDE доступна в той же сетевой среде, что и процесс PHP. В контейнере или виртуальной машине укажите доступный оттуда адрес машины с IDE.
PhpStorm: точки останова, стек и сопоставление путей
- Выберите интерпретатор PHP в настройках проекта. Для удалённой среды проверьте, что тесты и скрипты запускаются в нужном контейнере или на нужной машине.
- В настройках
PHP | Debugпроверьте порт Xdebug. Включите Start Listening for PHP Debug Connections. - Для удалённого веб-приложения добавьте сервер в
PHP | Serversи настройте Use path mappings. Например, удалённому каталогу/appдолжен соответствовать открытый в IDE корень проекта. - Поставьте точку останова на исполняемой строке и повторите запрос с триггером. В окне отладки выберите нужный кадр стека, чтобы увидеть локальные переменные конкретного вызова.
Step Over исполняет текущую строку и переходит к следующей, Step Into входит в вызываемую функцию, Step Out возвращает управление вызывающему коду. Если ошибка возникает только на отдельных данных, задайте условие точки останова, например $quantity === 0. Выражения в окне вычисления могут выполнять код. Вызов метода, который пишет в базу, способен изменить данные прямо во время отладки.
Для удалённого CLI PhpStorm может потребоваться явно выбрать сервер с нужным сопоставлением путей. Передайте переменную PHP_IDE_CONFIG со значением вида serverName=local-app, где local-app совпадает с именем сервера в настройках проекта.
VS Code для PHP: редактор с пошаговой отладкой
Чтобы использовать VS Code как PHP-редактор с отладкой, установите расширение PHP Debug. Подсветка, навигация по коду и подсказки типов могут обеспечиваться другими расширениями. Для пошаговой отладки нужен адаптер отладки в VS Code и Xdebug в интерпретаторе PHP.
Создайте .vscode/launch.json. Пример рассчитан на PHP в контейнере, где код лежит в /app, а в VS Code открыт локальный корень того же проекта. Для локального запуска с одинаковыми абсолютными путями удалите pathMappings.
{
"version": "0.2.0",
"configurations": [
{
"name": "Слушать Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
// Путь на стороне PHP соответствует локальному корню проекта.
"pathMappings": { "/app": "${workspaceFolder}" }
}
]
}Запустите конфигурацию «Слушать Xdebug» в разделе Run and Debug, поставьте точку и вызовите скрипт с триггером. При работе через Dev Containers или удалённый сеанс проверьте, где запущено расширение и где открыт порт. client_host должен указывать на среду, в которой слушает адаптер.
При выборе PHP IDE учитывайте повседневный сценарий. В PhpStorm настройки интерпретаторов, тестов, рефакторинга и отладки собраны в одной среде. В VS Code возможности можно собрать из отдельных расширений. Начать проверку в обоих случаях можно с одного скрипта и одной точки останова.
Почему Xdebug не подключается или пропускает точку
- Расширение видно в CLI, а запрос на сайте проходит без остановки. Проверьте загрузку расширения и режим
debugв веб-процессе. Убедитесь, что запрос попадает в ожидаемый контейнер и действительно содержит триггер. - Xdebug пытается подключиться, но получает отказ или тайм-аут. Проверьте, слушает ли IDE порт
9003, совпадает ли он сxdebug.client_portи доступен лиclient_hostиз среды PHP. Для диагностики временно задайтеxdebug.logкак абсолютный путь к файлу, доступному на запись процессу PHP. - Соединение есть, точка не срабатывает. Сравните путь к файлу, полученный от Xdebug, с файлом в рабочей папке. Проверьте сопоставление путей и версию кода в контейнере. Для первой остановки выберите строку с простым присваиванием или вызовом функции внутри ветки, которая точно выполняется.
- Точка срабатывает слишком часто. Проверьте
xdebug.start_with_requestи очистите cookie триггера после сеанса. Для часто вызываемого обработчика используйте условие точки останова по идентификатору или конкретному входному значению. - Остановка происходит, но причина ошибки пока не видна. Выберите кадр, где значение впервые получено или преобразовано. Для исключения поставьте остановку на выбрасывании и проверьте аргументы до входа в
catch.
Чек-лист отладки PHP
- Сохраните входные данные, на которых возникает ошибка, и сведите воспроизведение к одному запросу или запуску CLI.
- Сверьте версию PHP, загруженные расширения и INI-файлы в том процессе, где проявляется проблема.
- Проверьте тип и значение через
var_dump()в CLI или запишите нужные поля в журнал веб-приложения. - Для пошаговой отладки включите
xdebug.mode=debug, запустите прослушивание в IDE и повторите запуск сXDEBUG_TRIGGER. - Если соединения нет, проверьте журнал Xdebug, адрес и порт. Если соединение есть, проверьте пути к файлам и выберите исполняемую строку.
- После исправления повторите исходный запрос, проверьте результат и удалите временные дампы, триггеры и настройки диагностического журнала.
Частые вопросы
Как проверить, установлен ли Xdebug в PHP?
В CLI выполните php --ri xdebug. Для веб-запросов проверьте extension_loaded('xdebug') в локальной среде, поскольку PHP-FPM может читать другие INI-файлы. Для пошаговой отладки также нужен режим debug.
Почему PhpStorm подключается к Xdebug, но не останавливается на точке?
Проверьте, соответствует ли удалённый путь открытому в PhpStorm файлу, выполняется ли выбранная строка и совпадает ли версия кода на обеих сторонах. Для контейнера настройте сопоставление локального и удалённого каталогов.
Можно ли отлаживать PHP в VS Code без PhpStorm?
Да. Установите расширение PHP Debug в VS Code и Xdebug в среду исполнения PHP. Запустите конфигурацию прослушивания, поставьте точку останова и повторите запрос с триггером XDEBUG_TRIGGER.