Published on 2020-06-21 • Modified on 2020-10-18
- Php Docker Xdebug Phpstorm
- Phpstorm Setup Xdebug
- Phpstorm Xdebug Vagrant
- Phpstorm Xdebug Cli Docker
- Phpstorm Xdebug Ssh
- Configure Xdebug Phpstorm
- Phpstorm Xdebug Docker Cli
CLI Scripts: Drush. To debug custom Drush commands, make the following additional adjustments in PHPStorm settings: Go to Preferences Languages & Frameworks PHP Debug; Uncheck Force break at the first line when no path mapping specified; Uncheck Force break at the first line when a script is outside the project. You can run your scripts in console and debug them in the same way as. It turns out that Xdebug 3 is downloaded instead of the 2.X line. This caused my environment to stop responding to breakpoints I set in PHPStorm. These are the steps I followed to resolve the problem and get the PHP Xdebug PHPStorm combination going. Change configuration. First up: PHPStorm. I updated it to the latest version (2020.2.4).
In this post, we will see how to do step by step debugging with Xdebug, Symfony and PHPStorm. We will do a basic example where we will stop the execution of the Symfony code just before rendering a template to check the data passed to it. Let's go! 😎
» Published in 'A week of Symfony 704' (22-28 June 2020).
Prerequisite
I will assume you have a basic knowledge of PHP, Symfony and that you know how to modify your PHP configuration thanks to the php.ini file.
Introduction
Why this blog post? Well, because of this tweet:
PHP developers that don't use Xdebug for debugging are amateurs.
— Derick Rethans 🔶 (@derickr) June 20, 2020This is the kind of tweet I don't like, a typical troll, trying to make a generality of something more complex. It brings negativity as It can be interpreted by people not using Xdebug by:
“If you don't use Xdebug, you aren't a real developer.” 😔
Even it's not what Derick meant to say, it's what people may understand. There is no smiley. We don't know if the tweet is pure sarcasm or not. I wanted to answer at first. But what about transforming something negative to something positive and useful? 😀 That's why I decided to write this blog post. 🙂
Configuration
I use the following configuration, but it should be OK with previous versions of each of these components. Here, I use the Symfony binary to serve my application. If you use another type of setup (Apache, Docker...), you'll probably have to make small adjustments to the following instructions.
- PHP 7.4
- Symfony 5.2
- Xdebug 2.9.6
- PHPStorm 2020.3
Installation
I will assume you have a working PHP/Symfony installation. So first let's install Xdebug, it can be done with PECL:
If not done, activate the Xdebug extension in your php.ini file. You can find this file by running:
Verify that in this file, the xdebug.so (or .dll) library is loaded. You must see a line like the following (it can also be loaded in an external file like conf.d/ext-xdebug.ini):
If everything is OK, you should now see Xdebug when getting the PHP version:
Or when grepping the module list:
The debug bar also shows if Xdebug is available when you pass over the Symfony version number with your mouse:
Now that Xdebug is activated let's see how to configure it for PHPStorm.
Configuring Xdebug and PHPStorm
Xdebug
First, we must enable the remote option of Xdebug. Add the following parameter in your PHP configuration as we did previously:
We keep the other default parameters to keep the configuration as minimal as possible. So, with this setup, the port used by Xdebug is 9000 and the default IP address is 127.0.0.1. Check out the xdebug.remote_host and xdebug.remote_port parameters in the documentation.
PHPStorm
Now, let's check the configuration inside PHPStorm. Open the menu entry: Run > Web Server Debug Validation. You should see this window:
In the first parameter put the full path of your project public directory where is stored the Symfony front controller (generally public/index.php with Symfony 5). In the second parameter, put the local URL of your project. Then click on validate. If everything is OK, you should see ✅ like above. You can ignore the error of the last line, it seems to be a known problem, but it won't prevent the debugger from working. The final step is to tell PHPStorm to start listening to Xdebug connections. It must be done with the Run > Start Listening for PHP Debug connections menu entry.
Step by step debugging
Now that PHPStorm has validated our setup let's try to add our first breakpoint. Open one of your controllers and click between the line number and the start of the code editor panel of the line you want to stop the execution. A red disc 🔴 appears like this (at line 33 in this example):
Now, open your browser and access a page that calls the action where we put the breakpoint. If it works, PHPStorm gets back as the active window of your OS, and you get the following output:
As you can see, the code window is different from what we use to have. First, after the controller method declaration line, we have the values of the parameters received by the action. $_locale is 'en', $goals is an array with two keys, and lastly, $articleRepository is the Doctrine repository of the Article entity. Just below, we see that the line of the breakpoint is highlighted; this is to show that the code has stopped here like expected. Just before this line, after the declaration of the $data (at the right), we see the value of this new variable. It is empty as we just declared it.
Just below, in the debug panel, we have a Variables section where we can inspect all the local variables available at the breakpoint.
This panel is very convenient; we can see all the variables (even the globals) and expand them to check their content. We also find the function parameters ($_locale, $goals, $articleRepository). As this controller extends the Symfony AbstractController, we can notice that it has access to the dependency injection container ($this->container).
Now let's try to advance to the next 'step', to go to the next line. We can use the 'Step over' button (F6 with my setup).
As you can see the highlighted line has changed, it's now line n°34. We can see the value of the $date variable just above. This new $date variable is now part of the 'Variables' panel. We can continue like this until the end of the action to check that the $data array contains the correct keys and values and can be passed to the Twig template. To continue the execution of the script, click on the 'Resume program' button ⏯️ (F8).
If you don't need the breakpoint for now but want to keep it for later, you can right-click on it and deselect the 'Enabled' option. The red disc appears now as a circle. Refresh the page, and you will notice that the script doesn't stop anymore.
The browser extension
We can also install a browser extension (available for Firefox, Chrome, Safari, Opera) to disable/enable the debug on the fly. When disabled, nothing is caught by PHPStorm even there are still some active breakpoints. It is faster than deactivating the breakpoint manually or altogether disable Xdebug in the PHP configuration. It looks like this:
Conclusion
Et voilà! We have a practical step by step debugging workflow using Xdebug! What about telling Derick that we are now professionals PHP developers? 😁
About the original tweet, I really liked the answer of Jordi; this is precisely what I think:
I can see a debugger being valuable when code is very complex or unknown, and often use it in JS. In PHP code though I usually am familiar enough with what libs I use and find no benefit to debugging interactively. Like most things, it depends. No need to call people amateurs IMO
— Jordi Boggiano (@seldaek) June 20, 2020If you don't drink Guinness you are an amateur
— Gary Hockin (@GeeH) June 20, 2020PHP developers who don’t use @doctrineproject are amateurs.
— Jonathan H. Wage (@jwage) June 20, 2020Developers that don't use a computer to develop are amateurs
— Gregoire Pineau (@lyrixx) June 21, 2020PHP developers that don't write there own frameworks are amateurs
— Simon Bennett (@MrSimonBennett) June 20, 2020PHP developers that write bugs and need to debug are amateurs. https://t.co/NG5YtmdD3k
— Liam Hammett (@LiamHammett) June 20, 2020That's it! I hope you like it. Check out the links below to have additional information related to the post. As always, feedback, likes and retweets are welcome. (see the box below) See you! COil. 😊
They gave feedback and helped me to fix errors and typos in this article, many thanks to jmsche. 👍
Did you like this post? You can help me back in several ways: (use the Tweet on the right to comment or to contact me )
- Report any error/typo.
- Report something that could be improved.
- Like and retweet!
- Follow me on Twitter
- Subscribe to the RSS feed.
- Click on the More on Stackoverflow buttons to make me win 'Announcer' badges 🏅.
Thank you for reading! And see you soon on Strangebuzz! 😉
[🇬🇧] New blog post, this is my answer to the tweet: 'PHP developers that don't use #Xdebug for debugging are amateurs.' https://t.co/SPd8UIOrQ8 Proofreading, comments, likes and retweets are welcome! 😉Annual goal: 4/6 (66%) #php#strangebuzz#blog#blogging#debug#bug#blogging
— COil #StaySafe 🏡 #OnEstLaTech ✊ (@C0il) June 23, 2020Introducing CW: a cache watcher for Symfony
Adding a custom data collector in the Symfony debug bar
July 26, 2018To follow this tutorial, you must have the Xdebug extension installed on your container. In my example, I will use a Docker image of TheCodingMachine created by David Négrier. If you are starting a project, I recommend you to download one of our images here TheCodingMachine Docker PHP images
My base docker-compose.yml file looks like this:
Note: the PHP_EXTENSION_XDEBUG environment variable is specific to the thecodingmachine/php. It automatically configures Xdebug for the container.
Ports configuration
Keep in mind that PHPStorm opens port 9000 (by default) so Xdebug can connect to it. Our PHP container has Xdebug installed and Xdebug will try to connect to PHPStorm on port 9000 by default.
Out of the box, everything should be fine...
... except if port 9000 is already taken by another program on your host (your machine running PHPStorm).
Switching port
Port 9000 can be already used. In particular, if you are using PHP-FPM, the default port for PHP-FPM is 9000.This directly conflicts with the XDebug port.
If you want to use another port for Xdebug, follow the instructions below.
I recommend to use port 10000 instead.
Otherwise, just keep the default configuration port.
Registering your container server in PHPStorm
Php Docker Xdebug Phpstorm
First, click on edit configurations, on the top right of PHPStorm window.
Phpstorm Setup Xdebug
Then, follow the explanation in picture. All numbers are explained below.
(1) Click on add button
(2) Confirm it by clicking on PHP Web Page
(3) Define a name for your project
(4) Click on ... to add a debug server
(5) Once it's done, you are on debug server page. Click on '+' button to create a new one.
(6) Define a server name like docker_[your_project_name]
(7) Add your host on port 80 using Xdebug
(8) Don't forget to click on Use path mappings
(9) We need to add path mapping. Indeed, from the point of view of Xdebug, the PHP application runs in the '/var/www/html' (we are in a container!).But for PHPStorm, my project is in my host machine directory! So we need to map the root of your PHP application to the '/var/www/html' directory, as shown on the image above.
At this point, you should be able to put a breakpoint in your code, start a debugging session and get the application to stop on the breakpoint. Jump to chapter 'Run Xdebug' to see how to use Xdebug.
Xdebug CLI
All applications are not web-based. You might also want to debug a command-line application, from within your container.Let's see how to enable Xdebug for scripts (CLI)
In the docker-compose.yml, just add those environment variables
Remember that we are using our technical director's (David Négrier) images. That's why we can set PHP extensions, PHP .ini configurations into the docker-compose.yml.For more details, please look at this TheCodingMachine Docker PHP images.
(1) Enable the Xdebug extension
(2) If you are using a different Xdebug port, set your custom Xdebug port
(3) Add your Xdebug server name
(4) If you are using the default Xdebug port, please remove remote_port=[your_xdebug_port]. Otherwise, add your custom Xdebug port
Run Xdebug
Web
Place a breakpoint in your code and launch a debug session
Phpstorm Xdebug Vagrant
A new windows should open and you should access to PHPStorm debug bar.
Scripts (CLI)
Click on Start Listening for PHP Debug connections
The button should appear like this :
Place a breakpoint in your code.
Now, just go into your php-apache container using docker exec -ti [container_id] bash and run your script manually.
Addentum: Installing Docker integration in PHPStorm
There is a very useful PHPStorm extension to quickly and efficiently manage your docker containers.
For example:
- see the logs by container
- have access to bash in a clique
- quickly see environment variables
- clear or restart containers
Before starting
- You should check that the 'Docker integration' is enabled on your IDE
- Start the Docker daemon on you machine
- Move to your favorite Docker project in PHPStorm
Configuring Docker
Now everything should be good, just go to Preferences... > Languages and Frameworks > PHP
(1) Click on ... for openning the remote PHP interpreter
(2) Add a new CLI interpreter by clicking on From Docker, Vagrant, VM, Remote...
(3) Click on Docker (remember that you should start Docker daemon)
(4) Add a new server
(5) Select a server name
(6) Choose how to connect on Docker
(7) Make sure the connection is successful
(8) Select your favorite default image
(9) You need to set the path mapping for your code. By default, it's /opt/project in the container, just change it to /var/www/html
Done! Just click on the Docker button on the bottom of PHPStorm window.
About the author
Alexis is an experienced technical project manager who manages several projects including Eco-Emballages (CITEO). Graduate of EPITECH, Alexis is specialized in PHP frameworks (Symfony, Laravel, Mouf) and he masters Docker.
Related articles
Latest articles
Phpstorm Xdebug Cli Docker
Open-source matters
At TheCodingMachine, we are using open-source tools daily to build our projects. And since we and our clients are ripping huge benefits from these open-source products, we also try to 'give back' to the open-source community.
Freelance Developer?
At TheCodingMachine, we are always looking for top freelance developers to work with us on our next state-of-the-art project.
Interested in developing quality projects? We love good work and we pay fairly.
We are hiring!
Living in France? We are actively looking for developers and project leaders in our Paris and Lyon office.
About us
Phpstorm Xdebug Ssh
At TheCodingMachine, we strive to develop websites , extranets, intranets and business web applications in PHP and JavaScript for a wide range of clients.
Do not hesitate to contact us!
Best practices
Configure Xdebug Phpstorm
When writing code, we expect it to be of the best possible quality. To enforce this quality, we redacted our own 'best practices' described in a dedicated website.
We are happy to share those with you!
Packanalyst
Phpstorm Xdebug Docker Cli
We are the happy parents of Packanalyst, a free online service that lets you search any possible PHP class or interface referenced on Packagist.
Pretty useful for open-source developer to keep an eye on who is using what class/interface of your packages.