Getting Xdebug to Work with Atom Text Editor for PHP 8 Project
TLDR: It is possible.
If you’re a software developer or a person who works in IT, I think it’s safe for me to assume that you have heard of or used the Atom text editor, which is developed and maintained by the good people at GitHub, and (sadly?) now a property of Microsoft.
After playing around with multiple text editors over the years, Atom has grown on me to a point that, it has now become my go-to software development and also the multipurpose text/note typing tool. I haven’t found any reason to move away from it … until I tried to get it to work with Xdebug. It appeared that I cannot get Atom to work with Xdebug for some mysterious reason. I almost installed VS Code, but decided to give Atom another chance.
After some research and struggle I finally figured out how to get them to work together. Let me take you through the process if you’re interested.
My platform and software versions
OS: Elementary OS 5.1.7 (Hera) — built on Ubuntu 18.04.4
PHP version: 8.0.9
Atom text editor 1.58.0
Xdebug 3.0.4
And also web server of choice : Apache2
Installing and Configuring Xdebug
Xdebug is an extension for PHP, and provides a range of features to improve the PHP development experience. — xdebug.org
Whatever that means, all I wanted was to use it to debug a Laravel project.
In this article, I’m hoping to take you step by step on how it worked out for me.
Since I’m on Elementary OS, which is a Ubuntu derivative you can use apt or apt-get to install Xdebug. But, when you use aptor apt-get, you will not get the latest version. Therefore, if you want to get the latest version, you will have to use pecl.
Step 1) Installing pecl: If you don’t have pecl installed in your computer, you will need to install php-pear package to get it.
~$ sudo apt-get-install php-pear
Step 2) Installing Xdebug using pecl
When installing Xdebug with pecl you will run into an issue if you don’t have phpize installed in your system. Installing php-dev package would fix this. (I assume you already have PHP installed on your computer)
~$ sudo apt-get install php-dev
After installing php-dev run the following command to install Xdebug
~$ sudo pecl install xdebug
Step 3) Configuring Xdebug to work with your PHP installation.
After the installation, there will be a message which goes like:
You should add “zend_extension=/<path-to>/xdebug.so” to php.ini
One way to get Xdebug associated with your PHP setup is: as the above messages instructs, you can add the prompted extension configuration to your php.ini files. Typically you would have two php.ini files; one forphp-cliapplications (/etc/php/8.0/cli/php.ini) and another for web server’s PHP configuration (/etc/php/8.0/apache2/php.ini).
If you like to keep the Xdebug configuration centralized for all the different application environments, you can skip pasting the provided configuration to php.ini files and go to Step 4.
Step 4) Keep Xdebug configuration as a PHP configuration module.
First check if there’s a configuration file named xdebug.ini in your /etc/php/8.0/mods-available directory. If not, create a file with that name in it. You can use your favorite text editor to do that. Make sure you have the write permission to create and update files in the /etc/php/8.0/mods-available directory. I use Vim with sudo.
~$ sudo vim /etc/php/8.0/mods-available/xdebug.ini
Copy the prompted (after the Xdebug installation completed) zend_extension configuration into it.
zend_extension=/<path-to>/xdebug.soIf xdebug.so is located in a visible path to the PHP run time, you will only need the following line.
zend_extension=xdebugSave the file. Make sure it is owned by the root user and also has read permission.
~$ sudo chown root:root /etc/php/8.0/mods-available/xdebug.ini
~$ sudo chmod 0644 /etc/php/8.0/mods-available/xdebug.iniNow you have to run following command to make Xdebug available on your PHP environments.
sudo phpenmod xdebug
This command will create symbolic links (soft links) — to the configuration file that we created — in each directory where runtime configurations exist. The link names will not be the same as the file name. But they will contain the word xdebug in them.
Example:
/etc/php/8.0/apache2/conf.d/20-xdebug.ini
/etc/php/8.0/cli/conf.d/20-xdebug.iniFor changes to take effect on your web server, you will have to restart it.
Step 5) Check if Xdebug is correctly configured
If Xdebug is available for your PHP environment, you should see a similar output to the following when you run php --version on your terminal.
~$ php --version
PHP 8.0.9 (cli) (built: Jul 30 2021 13:03:21) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.9, Copyright (c) Zend Technologies
with Zend OPcache v8.0.9, Copyright (c), by Zend Technologies
with Xdebug v3.0.4, Copyright (c) 2002-2021, by Derick RethansCheck if you also have a line similar to the last line, which is only prompted if Xdebug is correctly configured.
Another way to check in a more informative way would be by placing a temporary PHP file in your web server’s document root with following content in it. After that you can load it in your web browser.
<?php
xdebug_info();If Xdebug is properly configured, this will give you a detailed webpage with lot of information that you may find interesting.
Before finishing the section about Xdebug installation and configuration, I would like to draw your attention to two more configurations. Since I’m trying to use Xdebug for debugging purposes we need to enable it’s debugging feature called “Step Debugger”. And also we should set up a log file to capture the Xdebug log messages. This is easily done by adding couple more lines to the previously created Xdebug configuration file. I use Vim again. But you can use a text editor of your choise.
sudo vim /etc/php/8.0/mods-available/xdebug.ini
Change the content to match the following.
zend_extension=xdebugxdebug.log=/tmp/xdebug.log
xdebug.mode=debug
After saving the file, you will have to restart your web server for the changes to take effect.
Getting Atom Ready for Debugging
When you install Atom in your computer, it will not contain a debugger for PHP. In order to debug your code using Atom, you will have to get the help of some plugins. Here, I’m going to tell you about the plugins that I used and how I got it to work. If you’re using different plugins, your experience may vary.
The first and the most important plugin is php-debug by Gabriel Womacks. You can install it by going through Edit -> Preferences and clicking on the “+ Install” on the resulting page. Type php-debug in the search box and install the first item in the list that comes up. You can get more information about this package on their documentation.
NOTE: php-debug is on its alpha. But looking at the number of downloads it appears somewhat popular.
Once the plugin is installed, you will be prompted with the following messages.
As you can see — in Image 3 — php-debug require the package atom-debug-ui by Caleb Champlin. If you click “Yes” in the message box, it will download and install it for you.
This article is written on 20th of August 2021 and as of now, there are some issues with the other two packages ide-php and atom-ide-ui when you try to use them with PHP 8. The package ide-php is yet to support PHP 8.
Also the package atom-ide-ui is making the UI rather confusing.
As you can see (image 4), it is possible to set two breakpoints for the same line. This happens because atom-ide-ui does also provide some of the similar UI features that php-debug and atom-debug-ui provides. (Tip: you only need the small dark blue break point. Not the large light blue one)
You can avoid this confusion by disabling atom-ide-ui's debugger. This thread (click here to see) explains the issue and how to disable the unwanted debugger.
All and all as of now (20th Aug, 2021), it’s better to avoid installing the last two suggested packages (ide-php and atom-ide-ui). It is possible to skip them as they are not required by php-debug.
How Xdebug Work
Since I’m talking about debugging a Laravel project, I wouldn’t be writing about CLI applications. There shouldn’t be much of a deviation from web server based debugging to CLI application debugging.
Since Xdebug is a very important component in the debugging process, you may think Xdebug is listening to the events triggered by the IDE. But reality it works the other way around. IDE opens up a port and listens for the debugging requests. Basically, once a debugging session is initiated, Xdebug sends a request to the IDE and gets the information about the break points. Similarly all the communication is done in the background while IDE gives you an abstract and user friendly experience.
When a request is received, Xdebug checks for the presence of something called a trigger. (Checkout the Xdebug documentation on xdebug.start_with_request and xdebug.trigger_value configurations for more information.)
In the Xdebug configuration file that we created earlier, if xdebug.start_with_requst is set to yes all the requests will be considered as debug requests. Otherwise you will have to set a trigger (which is also the default setting).
A trigger can either be an environment variable ($_ENV), HTTP GET ($_GET) parameter, HTTP POST ($_POST) parameter, or a cookie ($_COOKIE) named XDEBUG_TRIGGER. The value of the parameter (or the cookie) doesn’t matter unless xdebug.trigger_value is configured to check for specific value(s). For CLI applications you can set an environment variable (export XDEBUG_TRIGGER=1) to get the debugger triggered.
There are browser plugins like Xdebug helper for Firefox that you can use to set the triggers easily. You should be able to find a similar plugin for your favorite web browser.
Setting up Atom Text Editor
Now you have php-debug installed, go to “Edit -> Preferences”; click “Packages” and then click “Settings” button under php-debug to open up it’s settings page.
I would like to draw your attention to the fields “Server Listen Address” and “Server Listen Port”. Default values are 0.0.0.0 and 9000 respectively. Since your project is running on your local web server the default IP address would be OK. (I prefer to have 127.0.0.1 instead). What you have to make sure is the “Server Listen Port” value is equal to xdebug.client_port setting on your Xdebug configuration. After the ports are configured, close and re-open your Atom text editor and you would be ready to do some debugging.
First set a break point in one of your source files. I’ll use my index.php for this as it is easier for me to demonstrate. You can set a break point by either
a) Clicking on the gutter,
b) Right click -> Debug -> Toggle Breakpoint,
c) Alt+F9, or
d) On main menu, Packages -> Debug -> Toggle Breakpoint
For b,c and d options, you must first place your blinking cursor on the line, which you need to set a break point to.
Assuming you have your project running and you can visit it in your web browser, include the trigger parameter in the URL and hit “Enter” button.
Ideally this would trigger a debug session and your Atom text editor should respond accordingly. But I’ve noticed that, if you just restarted Atom, nothing’s going to happen. You might think of it as a bug. But, actually it makes sense to have it like that to reduce the resources usage. However, I find it weird to see no information about it available on PHP Debug Documentation. Yet I would cut them some slack given it’s still on its alpha. If I can make a suggestion, I’d like to propose them to add buttons (or a toggle button) to start and stop the debugger.
In order to avoid the above situation, I recommend you to start the debugger before you send the request from your web browser by clicking on “PHP Debug” icon at the Atom status bar.
My PHP Debug server IP address and port settings are set to 127.0.0.1 and 9003 respectively.
You can check it PHP Debug’s port is open by running the following command on your terminal.
~$ netstat -a -n | grep 'LISTEN 'The output should be something like this:
tcp 0 0 127.0.0.1:3306 0.0.0.0:* LISTEN
tcp 0 0 127.0.0.1:9003 0.0.0.0:* LISTEN
tcp 0 0 127.0.0.53:53 0.0.0.0:* LISTEN
tcp 0 0 127.0.0.1:631 0.0.0.0:* LISTEN
tcp6 0 0 :::45549 :::* LISTEN
tcp6 0 0 :::80 :::* LISTEN
tcp6 0 0 ::1:631 :::* LISTENAs you can see on line #2, I have my php-debug server running.
Now if you refresh your browser with the trigger parameter, your debug session should start.
Hope this article helps you. If you have any suggestions or questions, please feel free to let me know.
