Как использовать XDebug в VSCode

Ошибки раздражают. Они являются самой трудоемкой частью любого проекта по разработке программного обеспечения, и, несмотря на все желания разработчиков, не существует способа устранить их навсегда.

В этой статье вы узнаете, что такое отладчик, какие возможности есть в экосистеме PHP, а также как его установить и использовать.

Что такое отладчик

Отладчик является инструментом, который помогает находить причины ошибок. В частности, каждый инструмент имеет свой набор функций, но его цель всегда состоит в выполнении отладки.

Отладчик не исправит проблемы за вас (пока что), но он определенно поможет вам точно определить проблемы.

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

• Журналы (лог-файлы)
• Сообщения об ошибках

Они, конечно, очень важны, но обычно не дают много информации. Более важно то, что вы получаете информацию только после того, как скрипт полностью завершит свою работу, что затрудняет понимание контекста того, что происходило в момент возникновения ошибки. Это означает, что вам придется воссоздавать динамический поток программы в своей голове.

Отладчик позволит вам видеть содержимое переменных во время выполнения программы, а не после выполнения последней строки.

Еще одно большое преимущество использования такого инструмента заключается в возможности проверять значения во время выполнения без добавления кода (var_dump, print_r, и т.д.).

На практике отладчик представляет собой плагин или дополнение для среды разработки (IDE). В случае PHP это немного сложнее, поскольку PHP является интерпретируемым языком, который обычно работает поверх веб-сервера. В основном, каждый PHP отладчик состоит из двух частей: сервера (сам отладчик) и клиента (IDE).

Что такое XDebug

XDebug является расширением PHP, которое должно быть установлено на сервере разработки для активации возможностей отладки. Оно было создано и по сей день поддерживается Дериком Ретансом.

Основной критикой XDebug ранее были его громоздкая установка и процесс настройки. Однако с версии 3.0 все это уже в прошлом, как вы увидите в следующих разделах.

Как установить XDebug

Установка XDebug, конечно, зависит от вашей конкретной платформы. Однако, несмотря на различия, процесс достаточно прост. Если вы используете какую-либо версию AlmaLinux/CentOS/Ubuntu или подобную, достаточно выполнить следующую команду:

sudo apt-get install php-xdebug  //Ubuntu
sudo dnf install php-xdebug      //AlmaLinux/CentOS

Если у вас нет возможности использовать менеджер пакетов, вы все равно можете легко установить его через PECL:

pecl install xdebug

В качестве альтернативы, вы можете получить исходный код непосредственно из репозитория Git и скомпилировать его самостоятельно:

git clone https://github.com/xdebug/xdebug.git

Вы так же можете использовать официальную инструкцию, по крайней мере, имейте её под рукой. Верите или нет, это был единственный способ сделать это не так давно.

Как только бинарные файлы находятся на своем месте, вам необходимо включить xdebug через файл php.ini. Точный файл, который вам нужно изменить, зависит от вашей конкретной конфигурации. Может быть один огромный php.ini или по одному для каждого доступного расширения.

Если вы не знаете, какой выбрать для вашего случая использования, вы можете узнать с помощью простой команды:

php --ini

Как только вы найдете нужный файл (в идеале, файл подобный xdebug.ini), вот что вам следует внести в него:

zend_extension = xdebug

Затем, чтобы использовать XDebug, вам нужно его включить, установив хотя бы один режим выполнения:

xdebug.mode = develop,debug,trace

Теперь нужно перезапустить веб-сервер и можно начинать отладку!

Когда речь идет о режимах работы XDebug, есть некоторые тонкости. Если вы хотите узнать больше, прочтите эту статью и посмотрите это видео.

Настройка VSCode для XDebug

Как я упоминал ранее, в этом процессе есть две стороны:

• Сервер
• Клиент

На данном этапы вы узнали, как установить и настроить сервер, но если вы остановитесь только на этом, мало что изменится для вас.

Практический любая среда разработки (IDE) может использоваться для отладки PHP с помощью XDebug, но так как VSCode бесплатный и популярный я воспользуюсь им.

Если у вас еще нет установленного VSCode, вы можете получить его здесь.

Когда вы впервые запускаете свою среду разработки, вы увидите экран, подобный этому:

Если вы нажмете на значок отладки то увидите следующее:

Для начала отладки вам потребуется создать конфигурацию отладки. Щелкните на "create a launch.json file", чтобы создать конфиг. Вы увидите выпадающий список, подобный следующему:

В данный момент наилучшим способом продолжить будет выбрать "Install extension", где вы будете перенаправлены на экран, подобный следующему:

Если вы введете "php" рядом с "@category:debuggers", список вариантов будет сокращен только до плагинов, применимых к разработке на PHP. Но даже так все еще будет много вариантов для выбора. Хорошим правилом является выбор самого загружаемого плагина, вероятно это лучший вариант. Фактически, список отсортирован по этому критерию, так что если вы выберете первый, вы будете на правильном пути.

Нажмите "install":

Выбрав плагин PHP Debug можете увидеть множество деталей о расширении и инструкции по установке для серверной стороны.

Теперь вернитесь к экрану отладки и снова нажмите "create a launch.json file". Вы увидите тот же всплывающий список, но на этот раз будет доступен новый вариант:

Выберите этот вариант, и отредактируйте файл launch.json, который должен выглядеть следующим образом:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 0,
            "runtimeArgs": [
                "-dxdebug.start_with_request=yes"
            ],
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=${port}"
            }
        },
        {
            "name": "Launch Built-in web server",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-dxdebug.mode=debug",
                "-dxdebug.start_with_request=yes",
                "-S",
                "localhost:0"
            ],
            "program": "",
            "cwd": "${workspaceRoot}",
            "port": 9003,
            "serverReadyAction": {
                "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
                "uriFormat": "http://localhost:%s",
                "action": "openExternally"
            }
        }
    ]
}

Этой конфигурации должно быть достаточно на данный момент, но если вам нужны более тонкие настройки, всегда можно воспользоваться кнопкой "Add Configuration...". И так, когда мы настроили XDebug, давайте посмотрим, как он работает на практике.

Примеры использования

В этом разделе вы увидите два из наиболее типичных вариантов использования XDebug: отладка веб-приложения и отладка приложения командной строки (CLI). В качестве демонстрации я буду использовать код, расположенный в этом репозитории.

Отладка веб-приложения с XDebug и VS Code

Начните с возвращения к экрану отладки. В верхнем левом углу вы увидите выпадающий список "RUN AND DEBUG":

Выберите "Launch Built-in web server", нажмите play. Вы сразу попадете в браузер. Пока что ничего удивительного, верно? Подождите. Сейчас все станет интереснее.

Вернитесь в VS Code и откройте файл get_data.php:

Если вы наведете курсор мыши слева от номеров строк, вы увидите появление маленького красного кружка. Щелкните на нем в строке 9:

Поздравляю. Вы только что установили свою первую точку останова.

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

Что произошло? Выполнение скрипта остановлено, ожидая вашего действия. Если вы переключитесь в браузер, то увидите, что экран не полностью отрисован. Это связано с тем, что вызов Ajax не завершен. Теперь у вас есть все время, чтобы изучить, что происходило на сервере прямо перед завершением этого запроса.

Например, если вы посмотрите на верхнюю левую панель (Variables), вы увидите значения каждой переменной, доступной вашему скрипту до этого момента: после выполнения строк 1-8, но перед выполнением строки 9:

Так же есть блок управления с несколькими кнопами, чтобы продолжить выполнение скрипта по вашему усмотрению:

В частности, доступны три варианта:

• Step Over (Шаг через)
• Step Into (Шаг внутрь)
• Step Out (Шаг из)

Используя любой из них, вы сможете продвинуть выполнение на один шаг вперед, позволяя выполнить скрипт шаг за шагом. По мере продвижения вперед, значения переменных, отображаемые в верхней левой панели, будут обновляться в соответствии с динамическим потоком вашей программы. Это означает, что больше нет необходимости использовать var_dump повсюду, если вы этого не желаете.

Отладка при использовании CLI с XDebug и VS Code

Когда дело доходит до отладки приложения через CLI, процесс очень похож на то, что мы только что делали.

Предположим, вы хотите запустить get_data.php как скрипт командной строки вместо запуска через веб-сервер. Чтобы правильно отладить его, вам нужно изменить только настройку отладки, которую вы будете использовать.

Перейдите на экран отладки и выберите "Launch currently open script" из выпадающего списка конфигураций:

Затем, если вы нажмете кнопку play, вы сразу увидите, как выполнение остановилось на строке 9. Отсюда вы можете продолжить выполнение в своем собственном темпе.

При запуске приложений командной строки очень часто используются параметры, которые передаются через аргументы командной строки. Вы можете указать такие аргументы, добавив ключ args в файл launch.json, например, так:

{
  "name": "Launch currently open script",
  "type": "php",
  "request": "launch",
  "program": "${file}",
  "cwd": "${fileDirname}",
  "port": 0,
  "runtimeArgs": [
    "-dxdebug.start_with_request=yes"
  ],
  "env": {
    "XDEBUG_MODE": "debug,develop",
    "XDEBUG_CONFIG": "client_port=${port}"
  },
  "args": [
    "argOne"
  ]
}

Аналогично, вы можете добавить переменные среды через ключ env. Это может помочь при наличии нескольких конфигураций запуска.

Продвинутое использование XDebug

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

• Условные точки останова: возможность остановить выполнение кода только в том случае, если выполняется определенное условие. Это условие выражается в виде простого логического выражения на PHP.
• Наблюдения: мгновенное вычисление сложных выражений. Вы можете рассматривать панель переменных как самую простую форму наблюдений.
• Профилирование: анализ времени выполнения и узких мест. Это такая обширная тема, что она заслуживает отдельной статьи. Я просто хотел упомянуть об этом, чтобы вы знали, что это возможно.

Заключение

Старые, темные дни использования echo, var_dump, print_r и подобных для целей отладки остались позади. Для PHP-разработчиков, которые серьезно относятся к своему ремеслу и хотят сократить время поиска ошибок до абсолютного минимума, существует отличный инструмент XDebug .

Вопрос в том, будете ли вы применять его.