Run Xdebug on laravel sail docker Windows PhpStorm
I had the same problem for VS Code on a Linux workstation.
Maybe my solution could work for you, too.
Apparently, XDebug is not installed at all with Laravel Sail. In order to include it, you have to modify the Dockerfile
, edit docker-compose.yml
and rebuild the containers.
Here is how I did.
- I copied the Docker configuration Laravel Sail uses in a more convenient place:
cp -r vendor/laravel/sail/runtimes/8.0 ./resources/docker/
- I changed the
context
and added a variable underargs
in the first lines ofdocker-compose.yml
:
# For more information: https://laravel.com/docs/sailversion: '3'services: laravel.test: build: context: ./resources/docker/8.0 dockerfile: Dockerfile args: WWWGROUP: '${WWWGROUP}' XDEBUG: ${APP_DEBUG}...
So the context
points where I copied the original Docker configuration. I also decided to bind the new XDEBUG
arg to the value of the APP_DEBUG
variable inside the .env
file, in order to switch off XDebug in a production environment.
- Then, I changed the
Dockerfile
I copied before in order to include xdebug when building the containers. The script should also write the correct configuration options for Xdebug 3 insidephp.ini
:
FROM ubuntu:20.04LABEL maintainer="Taylor Otwell"ARG WWWGROUPARG XDEBUGWORKDIR /var/www/htmlENV DEBIAN_FRONTEND noninteractiveENV TZ=UTCRUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezoneRUN apt-get update \ && apt-get install -y gnupg gosu curl ca-certificates zip unzip git supervisor sqlite3 libcap2-bin \ && mkdir -p ~/.gnupg \ && echo "disable-ipv6" >> ~/.gnupg/dirmngr.conf \ && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys E5267A6C \ && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C300EE8C \ && echo "deb http://ppa.launchpad.net/ondrej/php/ubuntu focal main" > /etc/apt/sources.list.d/ppa_ondrej_php.list \ && apt-get update \ && apt-get install -y php8.0-cli php8.0-dev \ php8.0-pgsql php8.0-sqlite3 php8.0-gd \ php8.0-curl php8.0-memcached \ php8.0-imap php8.0-mysql php8.0-mbstring \ php8.0-xml php8.0-zip php8.0-bcmath php8.0-soap \ php8.0-intl php8.0-readline \ php8.0-msgpack php8.0-igbinary php8.0-ldap \ php8.0-redisRUN if [ ${XDEBUG} ] ; then \ apt-get install -y php-xdebug \ && echo "[XDebug]" > /etc/php/8.0/cli/php.ini \ && echo "zend_extension="$(find /usr/lib/php/20200930/ -name xdebug.so)" > /etc/php/8.0/cli/php.ini" \ && echo "xdebug.mode = debug" >> /etc/php/8.0/cli/php.ini \ && echo "xdebug.start_with_request = yes" >> /etc/php/8.0/cli/php.ini \ && echo "xdebug.discover_client_host = true" >> /etc/php/8.0/cli/php.ini ;\fi;RUN php -r "readfile('http://getcomposer.org/installer');" | php -- --install-dir=/usr/bin/ --filename=composer \ && curl -sL https://deb.nodesource.com/setup_15.x | bash - \ && apt-get install -y nodejs \ && apt-get -y autoremove \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*RUN setcap "cap_net_bind_service=+ep" /usr/bin/php8.0RUN groupadd --force -g $WWWGROUP sailRUN useradd -ms /bin/bash --no-user-group -g $WWWGROUP -u 1337 sailCOPY start-container /usr/local/bin/start-containerCOPY supervisord.conf /etc/supervisor/conf.d/supervisord.confCOPY php.ini /etc/php/8.0/cli/conf.d/99-sail.iniRUN chmod +x /usr/local/bin/start-containerEXPOSE 8000ENTRYPOINT ["start-container"]
- After stopping, rebuilding and relaunching the containers:
$ ./vendor/bin/sail stop$ ./vendor/bin/sail up --build -d
You can find out if XDebug is running:
$ ./vendor/bin/sail php -vPHP 8.0.0 (cli) (built: Nov 27 2020 12:26:22) ( NTS )Copyright (c) The PHP GroupZend Engine v4.0.0-dev, Copyright (c) Zend Technologies with Zend OPcache v8.0.0, Copyright (c), by Zend Technologies with Xdebug v3.0.1, Copyright (c) 2002-2020, by Derick Rethans
For VSCode only:
Inside
Preferences -> Settings
underDebug
you should check "Debug: Allow breakpoints everywhere".Change the default
launch.json
file:
{ // 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, "pathMappings": { "/var/www/html" : "${workspaceFolder}" } }, { "name": "Launch currently open script", "type": "php", "request": "launch", "program": "${file}", "cwd": "${fileDirname}", "port": 9000 } ]}
There is a discarded PR for optional Xdebug 3.0 support in laravel/sail (PHP 7.4 and PHP 8). Please follow the discussion.
Check the commit, what to change in Dockerfile
and docker-compose.yml.
Don't forget to set the variables in your .env
I got XDebug to work with a web request after some help from the posters above.
I have quite a bit of experience with PHPStorm and XDebug 2.x. I am new to docker so there may be better ways to fix this. I have not yet figured out how to run or debug tests that rely on the database connection from inside PHPStorm (right click on a test to debug). They run successfully with breakpoints if I am "listening" to sail test
(which will run the tests correctly) but PHPStorm can't find the MySQL database when running tests and I also get this error: "Xdebug: [Step Debug] Could not connect to debugging client. Tried: host.docker.internal:9003"
Update 1/18/21 to fix local environment within PHPStorm so that it can find the database and the rest of the Docker network. Now I can successfully run tests and debug from within PHPStorm. With the current build of PHPStorm 2020.3.1 You need to add the network name where it asks for the network mode. I will be reporting this to them so it may get addressed soon.
Get your network name by running docker network ls
. In this case it is myProjectName_sail.
NETWORK ID NAME DRIVER SCOPE8e8635ce01a6 bridge bridge local401307dbfaad host host localad8020ad629e myProjectName_sail bridge locald85a9668cade none null local
Enter this in PHPStorm Preferences>PHP>CLI Interpreter>...
On to the fix for debugging web requests:
What I have:
- Laravel Sail version 8.0
- Xdebug version 3.0
- PHPStorm version 2020.3 The version of PHPStorm is important as it supports PHP8 and Xdedbug 3.
What I did:
- I installed vim in my docker container by adding this line to the Dockerfile:
RUN apt-get -y install vim
- This lets me view/edit files easily by running
docker exec -it mySite.test_1 vim /etc/php/8.0/cli/php.ini
. - In this case I still edited the Dockerfile to generate the php.ini
You need to get your /etc/php/8.0/cli/php.ini
file to look like this (client_host was the key):
[XDebug]xdebug.mode = debugxdebug.start_with_request = yesxdebug.client_host = host.docker.internal
I added this to the Dockerfile as recommended by @Enea74. I was having trouble getting the conditional to return TRUE so I hard coded TRUE
here for now:
RUN if [ true ] ; then \ apt-get install -y php-xdebug \ && echo "[XDebug]" > /etc/php/8.0/cli/php.ini \ && echo "zend_extension="$(find /usr/lib/php/20200930/ -name xdebug.so)" > /etc/php/8.0/cli/php.ini" \ && echo "xdebug.mode = debug" >> /etc/php/8.0/cli/php.ini \ && echo "xdebug.start_with_request = yes" >> /etc/php/8.0/cli/php.ini \ && echo "xdebug.client_host = host.docker.internal" >> /etc/php/8.0/cli/php.ini ;\fi;
- I built the Docker containers by running
sail build --no-cache
- then
sail up -d
sail php -v
returns:
PHP 8.0.0 (cli) (built: Nov 27 2020 12:26:22) ( NTS )Copyright (c) The PHP GroupZend Engine v4.0.0-dev, Copyright (c) Zend Technologies with Zend OPcache v8.0.0, Copyright (c), by Zend Technologies with Xdebug v3.0.1, Copyright (c) 2002-2020, by Derick Rethans
Now In PHPStorm do the following. I think that it discovered many of these settings on its own: I don't remember setting all of these values:
Hopefully this will help someone.