Конфигуриране на Xdebug в PHPStorm

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

Например дебъгерът Xdebug се използва за PHP, а PHPStorm е една от най-популярните среди за разработка. След това нека видим как да конфигурираме Xdebug в PhpStorm за отстраняване на грешки на локален компютър и в Docker.

Конфигуриране на XDEBUG в PHPSTORM

Нека да поговорим за това как се извършва отстраняване на грешки на локалния сървър.

Нека разгледаме целия процес, като използваме Ubuntu и PHP интерпретатора, конфигуриран с Apache като пример. При други конфигурации пътищата до файловете може да са различни, но смисълът е същият. Дебъгерът Xdebug ви позволява да спрете изпълнението на кода, да прегледате стека на повикванията и съдържанието на променливите. Единственият му недостатък е, че няма удобен интерфейс за управление. Обикновено за управление на отстраняването на грешки се използват IDE. Но IDE не може да каже на дебъгъра да започне да отстранява грешки, защото отговаря само за кода. За тази цел ще ви е необходимо разширение за браузъра Debug Helper, с чиято помощ можете да активирате режима за отстраняване на грешки.

Първо трябва да инсталирате Xdebug. За да направите това, изпълнете:

$ sudo apt install xdebug

След като процесът на инсталиране на Xdebug завърши, трябва да конфигурирате програмата така, че когато стартирате сесия за отстраняване на грешки, тя да се опита да се свърже с нашия IDE, за да контролира отстраняването на грешки. За да направите това, добавете тези редове към файла /etc/php/7.4/apache2/conf.d/20-xdebug.ini във версията Xdebug 2:

$ sudo vi /etc/php/7.4/apache2/conf.d/20-xdebug.ini
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=false

За по-нова версия е най-добре да се използва друг формат:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9000

Нека разгледаме по-отблизо настройките. Първият параметър xdebug.mode - режим на отстраняване на грешки, възможните опции са:

• develop - позволява извеждането на допълнителна информация, отменя var_dump;

• debug - режим на изпълнение на кода ред по ред, това е режимът, от който се нуждаем в този случай;

• profile - профилиране;

• trace - проследяване на изпълнението на програмата.

Няколко режима се активират едновременно, когато са изброени в запетаи. Вторият ред xdebug.start_with_request определя как ще се стартира дебъгерът за режимите debug, trace и други подобни:

• yes - винаги, когато се изпълняват php скриптове;
• no - стартира се само от код, използващ специални функции;
• trigger - при поискване, като се използва специална променлива в $_ENV, $_POST, $COOKIE или друг масив. Тази опция е най-подходяща в този случай, за да не се стартира дебъгерът, когато не е необходимо.

Третата опция xdebug.discover_client_host е зададена на true, като в този случай xdebug се опитва да се свърже с хоста, предаден в HTTP_X_FORWARDED_FOR заглавието. Тъй като хостът е посочен в следващия ред, тази функция не е необходима в този случай. След това хостът на клиента, към който ще се свързваме за контрол на дебъгването, е 127.0.0.1 и порт 9000. Това е портът по подразбиране, използван в PhpStorm в момента. След като запазите настройките, трябва да рестартирате Apache, като използвате специална команда:

$ sudo systemctl restart apache2

След това трябва да конфигурирате PhpStorm. Стартирайте програмата, след което отворете менюто Run -> Edit Configurations (Изпълнение -> Редактиране на конфигурации). Ще се появи прозорец, в който трябва да конфигурирате дебъгъра.

Щракнете върху бутона + и изберете PHP Remote Debugger (Отдалечен дебъгер) от списъка, който се отваря:

Не променяйте нищо в настройките, просто посочете името на този метод за отстраняване на грешки. Ако не посочите сървъра, от който ще се очакват връзки, ще се приемат всички връзки.

Ако искате да промените порта, към който Xdebug ще се свързва, отворете Файл -> Настройки -> PHP -> Отстраняване -> DBGp Proxy. Тук можете да посочите желания порт.

Можем да кажем, че сега IDE е готов. Сега щракнете върху грешката в горната лента с инструменти. Програмата ще започне да чака дебъгерът да се свърже, а ние ще поставим няколко точки на прекъсване в кода, като просто щракнем пред реда с кода:

Сега остава само да конфигурираме браузъра.За Chrome можете да изтеглите специално разширение. Инсталирайте го и отворете страницата, която искате да дебъгвате. Щракнете върху иконата на разширението и изберете Debug (Дебъгване). Иконата на разширението ще стане зелена:

Опреснете страницата и се върнете в PHPStorm. Ако всичко е направено правилно, там ще започне сесия за отстраняване на грешки. При първото стартиране програмата може да поиска от вас да конфигурирате пътищата на локалните файлове, за да съвпаднат с пътищата на отдалечените файлове. За локалния сървър не е необходимо да конфигурирате нищо тук, просто щракнете върху Приемам:

След това дебъгерът ще спре изпълнението в избраната точка на прекъсване и в програмата ще се появи интерфейсът за дебъгване:

Сега нека разберем как да конфигурираме Xdebug PhpStorm и Docker.

Отстраняване на грешки в PHP в DOCKER

Docker може да бъде малко труден. Тъй като дебъгерът трябва да се свърже със самия IDE, трябва да препратите хоста към контейнера. В Windows това може да стане с помощта на адреса host.docker.internal. Но в Linux това не се случва по подразбиране. За да добавите такъв адрес, трябва да добавите следните редове към docker-compose:

extra_hosts:

host.docker.internal: host-gateway

Използваме следната структура на директориите:

Минимално необходимият docker-compose.yaml ще изглежда по следния начин:

version: '3.5'
networks:
  losst-network:
services:
  nginx:
    image: nginx
    ports:
        - '8094:80'
    volumes:
        - ./www/:/var/www/
        - ./conf/nginx:/etc/nginx/conf.d
    networks:
        - losst-network
  php-fpm:
    build: 
      context: ./conf/php-fpm
    extra_hosts:
      host.docker.internal: host-gateway
    volumes:
      - ./www:/var/www/
    networks:
      - losst-network

Просто декларираме два контейнера - nginx и php-fpm. Не правим никакви промени в първия, така че можем просто да вземем официалния образ, да монтираме папката с източника, конфигурационния файл и да пренасочим порта. Във втория контейнер е необходимо да се инсталира и конфигурира Xdebug, така че той ще трябва да бъде изграден на базата на официалния контейнер php. За същия контейнер е необходимо да се посочи директивата extra_hosts, без нея нищо няма да работи. Конфигурацията на Nginx също е съвсем стандартна:

server {
  listen 80;
  server_name _ !default;
  root /var/www/;
  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-XSS-Protection "1; mode=block";
  add_header X-Content-Type-Options "nosniff";
  index index.html index.htm index.php;
  charset utf-8;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  error_page 404 /index.php;
  location ~ .php$ {
    fastcgi_pass php-fpm:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    include fastcgi_params;
  }
}

Така се конфигурира обработката на PHP скриптове в контейнера php-fpm и пренасочването на несъществуващи URL адреси към index.php, което е съвсем стандартно за много рамки и CMS. В докерфайла на контейнера php-fpm той изглежда така:

Инсталирайте xdebug, като използвате pecl, и след това копирайте файла с конфигурацията му в контейнера. Файл:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

Xdebug 3 за PHP 8 е инсталиран в контейнера, тъй като старата версия вече не работи с тази версия на езика, затова се използва новият конфигурационен синтаксис. Ами хостът, host.docker.internal, който преди беше предписан в docker-compose.yaml. Конфигурацията на xdebug PHPStorm docker вече е завършена. След това можете да стартирате проекта:

docker-compose up --build

Сега, както и в предишния вариант, можете да активирате режима за отстраняване на грешки в браузъра, да опресните страницата и дебъгерът ще се свърже успешно с IDE, въпреки факта, че работи в Docker