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?
How?
Why?

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:

Info

Do check out his video with Kevin Dunglas, the creator of ApiPlatform if you also want to have the same revelation:
https://www.youtube.com/watch?v=H5nnVXYxY5o

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...

steve
├── api
├── compose.override.yaml
├── compose.prod.yaml
├── compose.yaml
├── helm
├── LICENSE
├── pwa
├── README.md
└── update-deps.sh

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:

1. create a new project of the /api directory
2. in the same window, create a second project of the root directory, and attach it to the /api project
   

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!

Build

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

Info

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!

Almost done...
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 From Docker...

Choose 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 PHP.

Click the + 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 /app

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:

xdebug.start_with_request=yes
xdebug.log_level=0

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:

XDEBUG_MODE=debug,develop

There are other ways to enable Xdebug, but IMHO, this is the easiest one.

Done !

You're all set...
Restart the docker environment:

docker compose up --pull --wait

Go to /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....

Conclusion

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...

Info

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/

Comments