From 363e6489328f471ecc781f22e61b9a74792b127c Mon Sep 17 00:00:00 2001 From: kujojotaromkdir Date: Sun, 16 Aug 2026 01:20:34 +0300 Subject: [PATCH 1/2] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B0=20=D1=81=D1=82=D0=B0=D1=82=D1=8C=D1=8F=20=D0=BE?= =?UTF-8?q?=D0=B1=20=D0=BE=D1=82=D0=BB=D0=B0=D0=B4=D0=BA=D0=B5=20=D0=BA?= =?UTF-8?q?=D0=BE=D0=B4=D0=B0=20=D1=81=20=D0=BF=D0=BE=D0=BC=D0=BE=D1=89?= =?UTF-8?q?=D1=8C=D1=8E=20Xdebug?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pages/get-started/debug-xdebug.md | 269 ++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 pages/get-started/debug-xdebug.md diff --git a/pages/get-started/debug-xdebug.md b/pages/get-started/debug-xdebug.md new file mode 100644 index 0000000..3ff19a0 --- /dev/null +++ b/pages/get-started/debug-xdebug.md @@ -0,0 +1,269 @@ +--- +title: Отладка кода с помощью Xdebug +description: Настройка Xdebug 3 для Bitrix Framework в Docker-окружении и BitrixVM. Подключение PhpStorm и VS Code, отладка агентов, cron-скриптов и AJAX-экшенов, профилирование. +--- + +Xdebug — расширение PHP для пошаговой отладки и профилирования. Вместо того чтобы расставлять по коду `echo` и `var_dump`, вы останавливаете выполнение скрипта в нужной строке и смотрите значения всех переменных прямо в IDE. + +Xdebug входит в состав официального [Docker-окружения](install-env.md#docker-obrazy) и виртуальной машины BitrixVM. Его нужно только включить и связать с IDE. + +{% note warning "" %} + +Не оставляйте Xdebug включенным на боевом сервере. Расширение существенно замедляет каждый хит, даже когда отладка не запущена. + +{% endnote %} + +## Как это работает + +Xdebug работает на стороне сервера и подключается к IDE по протоколу DBGp. Соединение инициирует именно сервер, а не IDE: + +1. IDE открывает порт и ждет входящее соединение — по умолчанию `9003`. + +2. В запросе к сайту передается триггер: cookie, GET- или POST-параметр `XDEBUG_SESSION`. + +3. PHP с включенным Xdebug видит триггер и подключается к IDE. + +4. IDE сопоставляет пути на сервере с путями в проекте и останавливает выполнение на точке останова. + +{% note info "" %} + +В Xdebug 3 параметры настройки переименованы. Инструкции с `xdebug.remote_enable`, `xdebug.remote_host` и портом `9000` относятся к Xdebug 2 и на актуальных версиях не работают. Проверить версию расширения можно командой `php -v`. + +{% endnote %} + +## Включение Xdebug в Docker-окружении + +Расширение `xdebug` уже входит в состав образа `bitrix24/php`, но по умолчанию отключено. + +Чтобы настройки не терялись при пересборке контейнера, задайте их в отдельном ini-файле и подключите его как volume. + +1. Создайте в папке проекта файл `xdebug.ini`. + + ```ini + zend_extension=xdebug.so + + xdebug.mode=debug + xdebug.start_with_request=trigger + xdebug.client_host=host.docker.internal + xdebug.client_port=9003 + xdebug.idekey=PHPSTORM + xdebug.max_nesting_level=512 + ``` + +2. Создайте файл `docker-compose.override.yml` рядом с `docker-compose.yml` из репозитория `env-docker`. + + ```yaml + services: + php: + volumes: + - ./xdebug.ini:/usr/local/etc/php/conf.d/zz-xdebug.ini:ro + extra_hosts: + - "host.docker.internal:host-gateway" + ``` + +3. Перезапустите контейнеры. + + ```bash + docker compose up -d + ``` + +4. Проверьте, что расширение подключилось. + + ```bash + docker compose exec php php -v + ``` + + В выводе должна появиться строка с Xdebug. + +{% note info "" %} + +Директива `extra_hosts` нужна в Linux, где имя `host.docker.internal` не резолвится автоматически. В macOS и Windows строку можно не указывать. + +{% endnote %} + +## Включение Xdebug в BitrixVM + +В виртуальной машине расширение уже установлено, а его конфигурация лежит в `/etc/php.d/`. Файл поставляется отключенным. + +1. Подключитесь к машине по SSH под пользователем `root`. + +2. Переименуйте файл конфигурации. + + ```bash + mv /etc/php.d/xdebug.ini.disabled /etc/php.d/xdebug.ini + ``` + +3. Приведите файл к виду, где `xdebug.client_host` — IP-адрес компьютера с IDE в той же сети, что и виртуальная машина. + + ```ini + zend_extension=xdebug.so + + xdebug.mode=debug + xdebug.start_with_request=trigger + xdebug.client_host=192.168.1.10 + xdebug.client_port=9003 + xdebug.idekey=PHPSTORM + xdebug.max_nesting_level=512 + ``` + +4. Перезапустите PHP-FPM. + + ```bash + /etc/init.d/php-fpm restart + ``` + +## Основные параметры + +| Параметр | Назначение | +| --- | --- | +| `xdebug.mode` | Режим работы: `debug` — пошаговая отладка, `profile` — профилирование, `develop` — расширенные сообщения об ошибках. Значения можно комбинировать через запятую. | +| `xdebug.start_with_request` | Когда запускать отладку: `trigger` — только при наличии триггера в запросе, `yes` — на каждом хите, `no` — никогда. | +| `xdebug.client_host` | Адрес компьютера с IDE, к которому подключается Xdebug. | +| `xdebug.client_port` | Порт, который слушает IDE. По умолчанию `9003`. | +| `xdebug.idekey` | Идентификатор сессии отладки. Должен совпадать со значением в IDE. | +| `xdebug.max_nesting_level` | Максимальная глубина вложенности вызовов. Ядро Bitrix Framework дает глубокий стек, поэтому значения по умолчанию может не хватить. | + +{% note tip "" %} + +Полный список параметров — в [документации Xdebug](https://xdebug.org/docs/all_settings). + +{% endnote %} + +## Настройка IDE + +{% list tabs %} + +- PhpStorm + + 1. Откройте *Settings > PHP > Debug* и убедитесь, что в блоке *Xdebug* указан порт `9003`. + + 2. Включите прослушивание входящих соединений — кнопка *Start Listening for PHP Debug Connections* на панели инструментов. + + 3. Откройте *Settings > PHP > Servers* и добавьте сервер: имя, хост сайта, порт. + + 4. Включите *Use path mappings* и сопоставьте корень проекта на локальной машине с корнем сайта на сервере: `/opt/www` для Docker-окружения, `/home/bitrix/www` для BitrixVM. + + 5. Поставьте точку останова и откройте сайт в браузере. При первом соединении PhpStorm предложит выбрать сопоставление путей — проверьте, что оно верное. + +- VS Code + + 1. Установите расширение *PHP Debug* (`xdebug.php-debug`). + + 2. Создайте файл `.vscode/launch.json`. + + ```json + { + "version": "0.2.0", + "configurations": [ + { + "name": "Listen for Xdebug", + "type": "php", + "request": "launch", + "port": 9003, + "pathMappings": { + "/opt/www": "${workspaceFolder}" + } + } + ] + } + ``` + + 3. Запустите конфигурацию *Listen for Xdebug* на вкладке *Run and Debug*. + + 4. Поставьте точку останова и откройте сайт в браузере. + +{% endlist %} + +{% note warning "" %} + +Неверное сопоставление путей — самая частая причина, по которой отладка «не работает»: соединение устанавливается, но точки останова не срабатывают или не видно значений переменных. Слева от двоеточия указывается путь **на сервере**, справа — путь к проекту **на локальной машине**. + +{% endnote %} + +## Запуск отладки + +При `xdebug.start_with_request=trigger` отладка включается только для тех запросов, в которых есть триггер. Это позволяет держать Xdebug настроенным постоянно и не мешать остальным пользователям сайта. + +Способы передать триггер: + +- **Расширение для браузера.** Xdebug Helper для Chrome или Firefox ставит cookie `XDEBUG_SESSION` по нажатию на иконку. Cookie сохраняется для всех запросов, включая AJAX. + +- **Параметр в адресной строке.** Добавьте к URL `?XDEBUG_SESSION=PHPSTORM`. + +- **Переменная окружения для CLI.** Используется для отладки скриптов командной строки. + + ```bash + XDEBUG_SESSION=PHPSTORM php script.php + ``` + +## Особенности отладки Bitrix Framework + +### Кеширование + +Если точка останова в компоненте не срабатывает, скорее всего, страница отдается из кеша и ваш код просто не выполняется. + +- Отключите композитный кеш на время отладки. Он отдает страницу из статического файла, не доходя до PHP-кода компонента. + +- Сбросьте кеш компонента или задайте параметр `CACHE_TIME` равным нулю. + +- Помните про кеш меню, инфоблоков и управляемый кеш — они также могут возвращать готовый результат без вызова вашего кода. + +### AJAX-экшены + +Запросы к контроллерам идут на `/bitrix/services/main/ajax.php`. Триггер в адресной строке для них не сработает — используйте расширение для браузера, которое ставит cookie: она отправляется вместе с XHR-запросами автоматически. + +### Агенты и cron-скрипты + +Агенты, запускаемые на хитах, отлаживаются как обычный запрос к сайту. Агенты на cron выполняются в CLI, где ни cookie, ни GET-параметра нет — триггер передается через переменную окружения. + +```bash +# Docker-окружение +docker compose exec --user=bitrix -e XDEBUG_SESSION=PHPSTORM php php -f /opt/www/bitrix/php_interface/cron_events.php +``` + +В IDE для CLI-скриптов нужно отдельное сопоставление путей — то же, что и для веб-сервера. + +### Долгие операции + +При пошаговой отладке скрипт стоит на точке останова, а веб-сервер и IDE ждут. Если отладка обрывается, увеличьте таймауты: `max_execution_time` в PHP, `fastcgi_read_timeout` в Nginx. + +## Профилирование + +Xdebug умеет собирать профиль выполнения — сколько времени заняла каждая функция. Это помогает найти причину медленных страниц. + +1. Добавьте в конфигурацию режим `profile` и папку для отчетов. + + ```ini + xdebug.mode=debug,profile + xdebug.start_with_request=trigger + xdebug.output_dir=/tmp/xdebug + ``` + +2. Передайте триггер `XDEBUG_PROFILE` в запросе — например, добавьте к URL `?XDEBUG_PROFILE=1`. + +3. Откройте полученный файл `cachegrind.out.*` в KCachegrind, QCacheGrind или в PhpStorm через *Tools > Analyze Xdebug Profiler Snapshot*. + +{% note warning "" %} + +Профилирование сильно замедляет хит и создает файлы в сотни мегабайт. Включайте его только по триггеру и следите за свободным местом на диске. + +{% endnote %} + +## Если отладка не запускается + +- **IDE не слушает порт.** Проверьте, что включено прослушивание входящих соединений и порт в IDE совпадает с `xdebug.client_port`. + +- **Порт занят другим процессом.** Убедитесь, что порт `9003` не используется другой IDE или контейнером. + +- **Xdebug не видит адрес IDE.** Из контейнера или виртуальной машины адрес локальной машины — не `localhost`. Для Docker это `host.docker.internal`, для BitrixVM — IP-адрес компьютера в локальной сети. + +- **Соединение есть, но точки останова не срабатывают.** Проверьте сопоставление путей. + +Диагностировать проблему помогает журнал Xdebug. + +```ini +xdebug.log=/tmp/xdebug.log +xdebug.log_level=7 +``` + +В журнале видно, пытался ли Xdebug подключиться к IDE и чем закончилась попытка. From 3be856008debbdfbc1d2ef8072dceff12d904722 Mon Sep 17 00:00:00 2001 From: kujojotaromkdir Date: Thu, 20 Aug 2026 22:42:02 +0300 Subject: [PATCH 2/2] =?UTF-8?q?=D0=A1=D0=BE=D0=BA=D1=80=D0=B0=D1=89=D0=B5?= =?UTF-8?q?=D0=BD=D0=B0=20=D1=81=D1=82=D0=B0=D1=82=D1=8C=D1=8F,=20=D0=B4?= =?UTF-8?q?=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D0=BB=20=D1=81=D1=81=D1=8B=D0=BB?= =?UTF-8?q?=D0=BA=D1=83=20=D0=BD=D0=B0=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC?= =?UTF-8?q?=D0=B5=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D1=8E=20Xdebug?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pages/get-started/debug-xdebug.md | 170 ++++-------------------------- 1 file changed, 22 insertions(+), 148 deletions(-) diff --git a/pages/get-started/debug-xdebug.md b/pages/get-started/debug-xdebug.md index 3ff19a0..7fb9114 100644 --- a/pages/get-started/debug-xdebug.md +++ b/pages/get-started/debug-xdebug.md @@ -1,33 +1,21 @@ --- title: Отладка кода с помощью Xdebug -description: Настройка Xdebug 3 для Bitrix Framework в Docker-окружении и BitrixVM. Подключение PhpStorm и VS Code, отладка агентов, cron-скриптов и AJAX-экшенов, профилирование. +description: Включение Xdebug в Docker-окружении и BitrixVM. Особенности отладки Bitrix Framework: кеширование, AJAX-экшены, агенты и cron-скрипты. --- -Xdebug — расширение PHP для пошаговой отладки и профилирования. Вместо того чтобы расставлять по коду `echo` и `var_dump`, вы останавливаете выполнение скрипта в нужной строке и смотрите значения всех переменных прямо в IDE. +Xdebug — расширение PHP для пошаговой отладки. Вместо того чтобы расставлять по коду `echo` и `var_dump`, вы останавливаете выполнение скрипта в нужной строке и смотрите значения всех переменных прямо в IDE. -Xdebug входит в состав официального [Docker-окружения](install-env.md#docker-obrazy) и виртуальной машины BitrixVM. Его нужно только включить и связать с IDE. +Расширение входит в состав официального [Docker-окружения](install-env.md#docker-obrazy) и виртуальной машины BitrixVM — его нужно только включить и связать с IDE. -{% note warning "" %} +{% note tip "" %} -Не оставляйте Xdebug включенным на боевом сервере. Расширение существенно замедляет каждый хит, даже когда отладка не запущена. +Описание всех параметров, режимов работы и способов запуска отладки — в [документации Xdebug](https://xdebug.org/docs/). {% endnote %} -## Как это работает - -Xdebug работает на стороне сервера и подключается к IDE по протоколу DBGp. Соединение инициирует именно сервер, а не IDE: - -1. IDE открывает порт и ждет входящее соединение — по умолчанию `9003`. - -2. В запросе к сайту передается триггер: cookie, GET- или POST-параметр `XDEBUG_SESSION`. - -3. PHP с включенным Xdebug видит триггер и подключается к IDE. - -4. IDE сопоставляет пути на сервере с путями в проекте и останавливает выполнение на точке останова. - -{% note info "" %} +{% note warning "" %} -В Xdebug 3 параметры настройки переименованы. Инструкции с `xdebug.remote_enable`, `xdebug.remote_host` и портом `9000` относятся к Xdebug 2 и на актуальных версиях не работают. Проверить версию расширения можно командой `php -v`. +Не оставляйте Xdebug включенным на боевом сервере. Расширение существенно замедляет каждый хит, даже когда отладка не запущена. {% endnote %} @@ -47,6 +35,9 @@ Xdebug работает на стороне сервера и подключае xdebug.client_host=host.docker.internal xdebug.client_port=9003 xdebug.idekey=PHPSTORM + + # ядро Bitrix Framework дает глубокий стек вызовов, + # значения по умолчанию может не хватить xdebug.max_nesting_level=512 ``` @@ -75,6 +66,8 @@ Xdebug работает на стороне сервера и подключае В выводе должна появиться строка с Xdebug. +5. В настройках IDE сопоставьте корень проекта на локальной машине с папкой сайта в контейнере — `/opt/www`. + {% note info "" %} Директива `extra_hosts` нужна в Linux, где имя `host.docker.internal` не резолвится автоматически. В macOS и Windows строку можно не указывать. @@ -83,7 +76,7 @@ Xdebug работает на стороне сервера и подключае ## Включение Xdebug в BitrixVM -В виртуальной машине расширение уже установлено, а его конфигурация лежит в `/etc/php.d/`. Файл поставляется отключенным. +В виртуальной машине расширение уже установлено, а его конфигурация лежит в папке `/etc/php.d/`. Файл поставляется отключенным. 1. Подключитесь к машине по SSH под пользователем `root`. @@ -103,6 +96,9 @@ Xdebug работает на стороне сервера и подключае xdebug.client_host=192.168.1.10 xdebug.client_port=9003 xdebug.idekey=PHPSTORM + + # ядро Bitrix Framework дает глубокий стек вызовов, + # значения по умолчанию может не хватить xdebug.max_nesting_level=512 ``` @@ -112,89 +108,7 @@ Xdebug работает на стороне сервера и подключае /etc/init.d/php-fpm restart ``` -## Основные параметры - -| Параметр | Назначение | -| --- | --- | -| `xdebug.mode` | Режим работы: `debug` — пошаговая отладка, `profile` — профилирование, `develop` — расширенные сообщения об ошибках. Значения можно комбинировать через запятую. | -| `xdebug.start_with_request` | Когда запускать отладку: `trigger` — только при наличии триггера в запросе, `yes` — на каждом хите, `no` — никогда. | -| `xdebug.client_host` | Адрес компьютера с IDE, к которому подключается Xdebug. | -| `xdebug.client_port` | Порт, который слушает IDE. По умолчанию `9003`. | -| `xdebug.idekey` | Идентификатор сессии отладки. Должен совпадать со значением в IDE. | -| `xdebug.max_nesting_level` | Максимальная глубина вложенности вызовов. Ядро Bitrix Framework дает глубокий стек, поэтому значения по умолчанию может не хватить. | - -{% note tip "" %} - -Полный список параметров — в [документации Xdebug](https://xdebug.org/docs/all_settings). - -{% endnote %} - -## Настройка IDE - -{% list tabs %} - -- PhpStorm - - 1. Откройте *Settings > PHP > Debug* и убедитесь, что в блоке *Xdebug* указан порт `9003`. - - 2. Включите прослушивание входящих соединений — кнопка *Start Listening for PHP Debug Connections* на панели инструментов. - - 3. Откройте *Settings > PHP > Servers* и добавьте сервер: имя, хост сайта, порт. - - 4. Включите *Use path mappings* и сопоставьте корень проекта на локальной машине с корнем сайта на сервере: `/opt/www` для Docker-окружения, `/home/bitrix/www` для BitrixVM. - - 5. Поставьте точку останова и откройте сайт в браузере. При первом соединении PhpStorm предложит выбрать сопоставление путей — проверьте, что оно верное. - -- VS Code - - 1. Установите расширение *PHP Debug* (`xdebug.php-debug`). - - 2. Создайте файл `.vscode/launch.json`. - - ```json - { - "version": "0.2.0", - "configurations": [ - { - "name": "Listen for Xdebug", - "type": "php", - "request": "launch", - "port": 9003, - "pathMappings": { - "/opt/www": "${workspaceFolder}" - } - } - ] - } - ``` - - 3. Запустите конфигурацию *Listen for Xdebug* на вкладке *Run and Debug*. - - 4. Поставьте точку останова и откройте сайт в браузере. - -{% endlist %} - -{% note warning "" %} - -Неверное сопоставление путей — самая частая причина, по которой отладка «не работает»: соединение устанавливается, но точки останова не срабатывают или не видно значений переменных. Слева от двоеточия указывается путь **на сервере**, справа — путь к проекту **на локальной машине**. - -{% endnote %} - -## Запуск отладки - -При `xdebug.start_with_request=trigger` отладка включается только для тех запросов, в которых есть триггер. Это позволяет держать Xdebug настроенным постоянно и не мешать остальным пользователям сайта. - -Способы передать триггер: - -- **Расширение для браузера.** Xdebug Helper для Chrome или Firefox ставит cookie `XDEBUG_SESSION` по нажатию на иконку. Cookie сохраняется для всех запросов, включая AJAX. - -- **Параметр в адресной строке.** Добавьте к URL `?XDEBUG_SESSION=PHPSTORM`. - -- **Переменная окружения для CLI.** Используется для отладки скриптов командной строки. - - ```bash - XDEBUG_SESSION=PHPSTORM php script.php - ``` +5. В настройках IDE сопоставьте корень проекта на локальной машине с папкой сайта на виртуальной машине — `/home/bitrix/www`. ## Особенности отладки Bitrix Framework @@ -210,7 +124,7 @@ Xdebug работает на стороне сервера и подключае ### AJAX-экшены -Запросы к контроллерам идут на `/bitrix/services/main/ajax.php`. Триггер в адресной строке для них не сработает — используйте расширение для браузера, которое ставит cookie: она отправляется вместе с XHR-запросами автоматически. +Запросы к контроллерам идут на `/bitrix/services/main/ajax.php`. Триггер отладки в адресной строке для них не сработает — используйте расширение для браузера, которое ставит cookie `XDEBUG_SESSION`: она отправляется вместе с XHR-запросами автоматически. ### Агенты и cron-скрипты @@ -218,52 +132,12 @@ Xdebug работает на стороне сервера и подключае ```bash # Docker-окружение -docker compose exec --user=bitrix -e XDEBUG_SESSION=PHPSTORM php php -f /opt/www/bitrix/php_interface/cron_events.php +docker compose exec --user=bitrix -e XDEBUG_SESSION=PHPSTORM php \ + php -f /opt/www/bitrix/php_interface/cron_events.php ``` -В IDE для CLI-скриптов нужно отдельное сопоставление путей — то же, что и для веб-сервера. +Для CLI-скриптов в IDE нужно отдельное сопоставление путей — такое же, как для веб-сервера. ### Долгие операции -При пошаговой отладке скрипт стоит на точке останова, а веб-сервер и IDE ждут. Если отладка обрывается, увеличьте таймауты: `max_execution_time` в PHP, `fastcgi_read_timeout` в Nginx. - -## Профилирование - -Xdebug умеет собирать профиль выполнения — сколько времени заняла каждая функция. Это помогает найти причину медленных страниц. - -1. Добавьте в конфигурацию режим `profile` и папку для отчетов. - - ```ini - xdebug.mode=debug,profile - xdebug.start_with_request=trigger - xdebug.output_dir=/tmp/xdebug - ``` - -2. Передайте триггер `XDEBUG_PROFILE` в запросе — например, добавьте к URL `?XDEBUG_PROFILE=1`. - -3. Откройте полученный файл `cachegrind.out.*` в KCachegrind, QCacheGrind или в PhpStorm через *Tools > Analyze Xdebug Profiler Snapshot*. - -{% note warning "" %} - -Профилирование сильно замедляет хит и создает файлы в сотни мегабайт. Включайте его только по триггеру и следите за свободным местом на диске. - -{% endnote %} - -## Если отладка не запускается - -- **IDE не слушает порт.** Проверьте, что включено прослушивание входящих соединений и порт в IDE совпадает с `xdebug.client_port`. - -- **Порт занят другим процессом.** Убедитесь, что порт `9003` не используется другой IDE или контейнером. - -- **Xdebug не видит адрес IDE.** Из контейнера или виртуальной машины адрес локальной машины — не `localhost`. Для Docker это `host.docker.internal`, для BitrixVM — IP-адрес компьютера в локальной сети. - -- **Соединение есть, но точки останова не срабатывают.** Проверьте сопоставление путей. - -Диагностировать проблему помогает журнал Xdebug. - -```ini -xdebug.log=/tmp/xdebug.log -xdebug.log_level=7 -``` - -В журнале видно, пытался ли Xdebug подключиться к IDE и чем закончилась попытка. +При пошаговой отладке скрипт стоит на точке останова, а веб-сервер и IDE ждут. Если отладка обрывается, увеличьте таймауты: `max_execution_time` в PHP и `fastcgi_read_timeout` в Nginx. \ No newline at end of file