Atom’s docs and most web articles still refer to Xdebug 2 configuration and older versions of PHP rather than the current versions of both.
Atom is an excellent debugging client when connected to a remote Drupal (with Xdebug 3 and PHP 8.1) and sufficient for my Drupal dev needs. Here’s how I set it up.
This is opinionated advice drawn from my experience with my simple use case. I hope it is useful to you and others with similar needs to mine.
We aim for Low Code site development, to do the minimum Drupal programming of custom modules and themes, but occasionally it is necessary for me to dust off the development tools and then try to remember what I was doing those months ago when I last had to. “IDE” tasks I need to do are chiefly code editing with some debugging and inspection using Atom as an Xdebug client.
Providing that Xdebug is set uo on the dev server with the correct
php.ini configuration, Atom can be set up as an Xdebug client really easily so I thought that I would record what is needed. I have the following items in my component stack.
Apache 2.4.41 running with PHP-fpm and APCu cacheing on Ubuntu 20.04 Linux. (In the past I haven’t reliably been able to use Xdebug with Nginx and PHP-fpm)
PHP 8.1 - (PHP 8.0 and later require Xdebug 3)
Xdebug 3 which has different, simpler
php.inisettings than previously was the case in Xdebug 2
MacOS (Monterey 12) as the host machine in which Atom is the Xdebug client and PHP Xdebug running in the guest virtual dev machine
Parallels Desktop providing the virtualisation for …
the virtual Ubuntu Linux guest dev machine
So we want to have:
a connection between Xdebug running on the remote testing virtual server and
the Xdebug client running on our host machine as an Atom plugin.
We also want a browser set up with the ability to switch Xdebug step tracing on and off for each http request it makes to the remote server.
Atom (developed by GitHub and contributors) is free of charge and a delight to use. It has (contributed) plugin packages that together can provide IDE-like functionality for many Drupal dev tasks.
I assume that you have the latest Atom installed.
Install Atom’s PHP-Debug package.
You will be asked to install several other dependent packages. I ended up disabling the optional packages IDE-PHP and ATOM-IDE-UI which caused errors as they seemed to be out of sync with PHP-Debug and didn’t seem to offer any extra functionality worthy of spending time investigating the error. There is one dependent package that is required ATOM-DEBUG-UI. Note that PHP-Debug’s GitHub page has example
php.inisettings for Xdebug 2. Ignore these. We’ll be using Xdebug 3 because it is compatible with PHP 8.1 (more on this below)
Configure Atom’s PHP-Debug settings.
Path mappings. Drupal programs are in the
/var/www/drupal/webof the guest-remote VM whereas I am editing them in the host-local subdirectories of
/Users/me/mysite/weband so the Atom PHP-Debug path mapping is a JSON dictionary expression like this:
The default for Xdebug 3 is 9003 but I set mine to 9000 on the remote and left Atom’s PHP-Debug default 9000 on the client.
IDE Key. In Xdebug 3 this is just another trigger. In any case I set PHP-Debug’s IDE key as
xdebug-atomand will specify this as the trigger on the remote VM.
Remote testing server setup
Install Xdebug on the remote / guest VM
sudo apt install php8.1-xdebug
apt installwill have created
; file /etc/php/8.1/fpm/conf.d/20-xdebug.ini [XDebug] zend_extension=xdebug.so xdebug.mode=debug xdebug.start_with_request=trigger xdebug.trigger_value=xdebug-atom xdebug.discover_client_host=True xdebug.client_port=9000 xdebug.log=/tmp/xdebug.log
For good measure you should make
Restart the remote system’s web server.
AFAIK it is sufficient to
sudo systemctl restart php8.1-fpmbut for good measure
sudo systemctl restart apache2also.
Maybe someone would be kind enough to comment below as to whether restarting Apache is really necessary when using PHP-fpm. I don’t think that it is.
Edit the extension’s settings to use the IDE Key
If you mainly want to set breakpoints and inspect variables then I think the concepts of
IDE Key and
trigger are somewhat merged in Xdebug 3, so I leave the profile triggers and trace triggers blank.
Set up breakpoints
In Atom “Move the cursor to a line you want to break on and set a breakpoint by pressing
If everything worked correctly, you can now use the various buttons/commands to step through the script.”
The Atom client’s PHP Console panel indicates when the server is connected. The PHP Debug panel lists the breakpoints you have set and allows you to inspect the values of variables at such breakpoints.
A note on PHPStorm
I have been a JetBrains subcriber for many years but don’t need PHPStorm at this time. PHPStorm is a superb product and very useful and, as I have blogged previously, is not only a useful Xdebug client, but a fully-fledged IDE with extensive and excellent help resources.
But PHPStorm is not easy to set up for Xdebug. There are several PHPStorm-specific concepts to grasp when configuring it and so, having done this several times over the last decade, I am of the opinion that the learning curve is actually more demanding than that of setting up Xdebug from scratch. So, you can justify your investment in time and money in relation to the scale of the project in which you and your team are engaged.