PHP: Xdebug in PHPStorm on, almost, all docker environments, is easy¶
Xdebug is a very powerful debugging tool, well actually, probably the God tool of all tools if you're debugging.
It lets you pause the execution of your app and lets you analyze, in full context what is happening, step debug etc etc.
Even though the setup has gotten drastically easier, thanks to the awesome effort Derick Rethans, its creator, has put in it, it still appears to scare of some developers... Let us hope this DevNote helps.
I have not slept for days, almost a week, after I read Steve's tweet talking about Xdebug:
Not you Steve!
How can you do this to Derick, one of the most brilliant minds in the PHP community?
So I decided I could no longer live with this and that I ought to, at least, try to show Steve the way...
Git the code¶
Now I know Steve is currently playing with ApiPlatform as he finally, after more than four years, discovered he has been doing APIs all wrong:
Do check out his video with Kevin Dunglas, the creator of ApiPlatform if you also want to have the same revelation:
So, let us set up a real quick ApiPlatform project and configure Xdebug. (For the full ApiPlatform documentation, see here)
Generate a Github clone (here),
git clone and your done...
Now the default ApiPlatform comes with a lot of features, but in the end, the
/api directory is just a PHP project encapsulated in a certain Docker environment...
How it is encapsulated really is not very relevant... Except for one thing... The setup of your PHPStorm environment.
Setup the PHPStorm project¶
Now, normally one would just create a new project of the root dir... Yet, in that case, the Symfony Support plugin, which is quite handy, will have some trouble figuring out where the files are located (and I have not found a setting that would make it possible to set a root path for the plugin).
I have found it easier to do this in two steps:
- create a new project of the
- in the same window, create a second project of the root directory, and attach it to the
In the end, PHPStorm is smart enough to notice
/api is in the root directory... But the Symfony Support plugin will work out of the box... Brilliant!
Following the documentation, we only need to build the docker environment, and we're all set.
# in the root directory
docker compose build --no-cache
Once it is built, start the container:
docker compose up --pull --wait
If you want to make your life easier with those docker commands, check out this article: the MakeFile for Symfony, ApiPlatform & FrankenPHP projects
AND YOUR ALL DONE!
Go to https://localhost, accept the local SSL cert, and you'll see the project running.
Yes, it is that easy!
Click on API to see the API in action, and play with it... (Do check out the future details in the ApiPlatform mentioned above).
Now, the nice thing about FrankenPHP, that bundles the ApiPlatform package, is that it comes preloaded with Xdebug out of the box!
Back to PHPStorm, for the final setup:
Configure the PHPStorm project¶
There are 3 steps:
1. Setup the runtime¶
Go into the settings, select the
PHP tab, and click on the
... to set the CLI interpreter:
In the upper left corner click on the
+ to add a new one, and select
Docker compose, select the configuration file,
./compose.yaml at the root of your project and finally, select
php as the service:
Click OK, and you're all done:
You can give the interpreter a name... and as you can see Xdebug is ready!
2. Folder mapping¶
Back to the settings, go to the
Server tab under
+ button to add a new configuration, give it a name, set
localhost as host,
443 as port, check the
Use path mappings... and simply map the
/api directory to
3. Xdebug setup¶
The final step is a personal preference...
You can either chose to enable Xdebug with a cookie or with a URL parameter, but I personally prefer to have it running all the time and only listen to it when I need to.
In PHPstorm, open
api/frankenphp/conf.d/app.dev.ini and add the following lines:
The first one will make sure Xdebug is running for every request, the second one disables the Xdebug logging which would pollute your console.
Finally, create an
.env file at the root of the project and add the following lines:
There are other ways to enable Xdebug, but IMHO, this is the easiest one.
You're all set...
Restart the docker environment:
docker compose up --pull --wait
/api/index.php, set a breakpoint wherever you want and click the
Start listening for PHP Debug Connections (you can easily add a shortcut for this, I've set Alt+Shift+X), and go to https://localhost/docs
Now you can set breakpoints wherever you want, execute a query, or a CLI command, and Xdebug will pause the execution and lets you analyze the full context of your app.
Happy Debugging !
My pleasure Steve....
This procedure is more or less the same for any Docker environment as long as it bundles Xdebug...
Adding Xdebug to a Docker environment is a little out of scope of this DevNote...
As I said, « Adding Xdebug to a Docker environment is a little out of scope of this DevNote... »
Say no more... Andreas Heigl wrote about it here: https://andreas.heigl.org/2023/11/07/xdebug-in-docker/