As with many of my blog posts, this one also started with a Tweet
I’ve been using Xdebug on Ubuntu in PHPStorm for going on 4 years now, and as I’ve been actively blogging about my development set up, I thought for sure I’d written about this. Turns out I had not, and so here we are.
Why Zero-configuration debugging?
To be honest, if you can read the Zero-configuration debugging help doc from PHPStorm, you probably don’t need this article. I think that doc might even be the reason I’ve never blogged about it. It really is the quickest way to get up and running debugging your code inside PHPStorm with Xdebug.
The PHPStorm Zero-configuration debugging process requires almost zero configuration. Install a few tools, turn a few things on, hit refresh in your browser, and you’re step debugging your PHP code.
It might not be as completely integrated into your PHPStorm environment as a fully configured set up, but it quickly gets you into the world of debugging PHP line by line.
A note on local environments. This article covers using either Apache or Nginx installed directly on your Ubuntu machine with PHP, and not running inside any virtual environment. It is possible to use this set up if you are using some form of virtualisation, but that’s a topic for another post.
So let’s dive into the details.
Install Xdebug
The Xdebug installation docs include a detailed list of install commands for a wide range of Linux operating systems. On Ubuntu, since 18.04, it’s as straightforward as running the following command.
sudo apt-get install php-xdebugThe instructions also include how to install a specific version of Xdebug if you’re using a different version of PHP than what is available on your version of Ubuntu’s repositories, like if you’re using Ondřej Surý’s PPA.
A note on versions. Depending on your Ubuntu version, the version of Xdebug in the repository might be out of date. For example on my old 20.04 LTS workstation, the Xdebug version is 2.9.3 for some reason, while on my 20.04 LTS laptop it’s 3.0.1, and the latest version is 3.0.2. It’s recommended to use the latest version available version of Xdebug, but I suggest first getting used to it by using the version available in the Ubuntu repositories, before attempting a manual install to make sure you’re always on the latest and greatest.
Once Xdebug is installed, you need to tell PHP to use it, which requires some additions to your php.ini. First, check where the xdebug.so (“Shared Object”) file is located. This is usually in your /usr/lib/php/ directory, in a directory named after a date (eg 20190902). Inside it you’ll find the xdebug.so file, which you need to configure by adding it to your php.ini.
zend_extension="/usr/lib/php/20190902/xdebug.so"You also need to enable Xdebug debugging , which depending on your Xdebug version, requires a slightly different php.ini line.
;Xdebug 2.x
xdebug.remote_enable=on;Xdebug 3.x
xdebug.mode=debugThen, restart your web server, and check that Xdebug has been enabled.
php --versionYou should see something like this, which confirms Xdebug is enabled with PHP.
PHP 7.3.25-1+ubuntu20.04.1+deb.sury.org+1 (cli) (built: Dec 26 2020 10:32:51) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.3.25, Copyright (c) 1998-2018 Zend Technologies
with Zend OPcache v7.3.25-1+ubuntu20.04.1+deb.sury.org+1, Copyright (c) 1999-2018, by Zend Technologies
with Xdebug v3.0.1, Copyright (c) 2002-2020, by Derick Rethans
Install one of the Xdebug Browser debugging extensions for your browser
The PHPStorm help docs have a list of all the different popular browsers, and the extension(s) needed for each. Essentially all these extensions do is allow you to set a special GET/POST or COOKIE parameter needed to trigger debugging from a browser request. You could do this yourself manually, but who has time for manual processes?
Set up PHPStorm for debugging
At this point, it’s a good idea to validate the Xdebug configuration within PHPStorm. Open the PHPStorm Settings (File -> Setttings) and browse to Languages and Frameworks -> PHP -> Debug.
Under Pre-configuration, click the Validate link.
Make sure the Path to create validation script is set to the web root for your project, and the URL to validation script points to the local URL that you’d use to browse to your projects web root. Click the Validate button, and you should see a list of validation checks passing.
The last thing you need to do is set PHPStorm to start listening for PHP debug connections from the browser. You can set this from the Run menu in PHPStorm.
Once that’s done, you’re good to go.
Debugging
You can now start adding breakpoints in your code, by clicking in the grey area next to your line numbers in PHPStorm. The breakpoint appears as a red dot, next to the line you want to start debugging at.
You can then use the browser extension for your browser you installed earlier, to turn debugging on from the browser, which ensures the browser will send the special GET/POST or COOKIE parameter on subsequent requests, and refresh the web page.
If you’ve set it all up right, you should see your browser page sit on a loading screen, while the debug toolbar pops up at the bottom of your PHPStorm window.
Success! You can now step through your code, and debug what it’s doing.
Final note, the first time you trigger a debug session for a site/project, PHPStorm will probably pop up a window detecting an incoming debug connection. It then asks to confirm some details about the connection. Mostly you can leave this as the defaults, but it’s good to just check that everything is set correctly.
I’ve found the zero-configuration debugging set up to be the quickest way to start step debugging on PHPStorm, and I’ve not used anything else in the past 4 years. I especially enjoy how I can enable everything in the IDE, but then just turn on the browser extension, to kick things off, and turn it off again when I don’t need it.
During development I still use things like die() or dd()when I want to quickly see the contents of things, and I’ve started using PsySH via Laravel’s artisan tinker or via WP-CLI more and more to test snippets of code and see their output, but Xdebug is essential when I’m hunting down bugs or hard to replicate edge cases.
If you do end up setting up Xdebug, and you find it useful, please consider supporting the project.
Leave a Reply