This article is related to this one and is build on top of the setup described there. You can also use a similar setup for generic xdebug remote debugging with PhpStorm. The main difference is here, that I recommend to SSH remote forward the debug port 9000. I'm sure I will describe this in a later article in more detail.
1. Open our brand new project
The first step is to open our project in PhpStorm under
File > New Project from Existing Files. In the following window select
Sources files are in a local directory, no Web server is yet configured. and press
In the next window we select the path where our project is stored and we click on
In the next dialog you can choose what you want. We open it here in the current window.
We should now see our opened project and can go on with configuring xdebug.
2. Debug configuration
On the top of our main menu we click on
run and should see this:
Edit Configurations is our next step. We see now this:
With the '+' symbol in the top of the left corner, we open this menu:
After clicking on
PHP Remote Debug, we get a next dialog where we for now enter the following marked details. We can find the ide session key in our app.env.dist file.
As we can see in the lower error message "Error: Server is not selected", we can assume that we need to configure a server as next. For doing this, we click on the "…" in the server line, where we currently see "<no server>". In the dialog coming next we see, that we really have no server configured yet. So let's click on the "+" in the above left corner again.
In the next screen we enter the following:
app_host is important here, because this is the name we configured also in our app.env.dist file with
PHP_IDE_CONFIG=serverName=app_host. This setting allows us to easily debug CLI commands from the console of our app container.
The second important thing here is to setup the path mappings, for this we need to enable
Use path mappings (select if the server is remote or symlinks are used). We only need to set the mapping of our local
app folder here. Based on our docker-compose.yml file under the app service, this folder is mounted under
/var/www/html inside our app container.
We are now done with our basic xdebug and server setup on the PhpStorm side.
The only thing I recommend to do, is setting the number of maximum simultaneous debug connection to a higher value (default is 1). The problem is, if we don't do this, we are only able to debug just one thread at once and we need more than one. For example, if we trigger a CLI command which triggers something else which then establish a new request. A new request means a new thread in the case of PHP. To prevent this, we simply increase this number. For this we open
File > Settings… and going to
Languages & Frameworks > PHP > Debug. Let's change now the default
5 in our example.
OK and we are done here.
3. Test our configuration
We can simply test our debug configuration by opening the
app/public/index.php file and place a breakpoint at line 19 for example.
Ignore the red underlined
?? here, this is because we have currently the wrong PHP version configured.
Now, in our main menu, we click again on
Run and enable debug listening.
If we open now http://localhost we should see that PhpStorm is pausing at our breakpoint.
Congratulations, our debug environment is working!