Xdebug is an extension for PHP to assist with debugging and development.
Xdebug helps you resolve issues in PHP code by providing debugging tools. You can integate it with your interactive developer environment (IDE) or an editor. Debuggers have something of a reputation for being hard to make work, and this is no exception but the benefits outweigh the effort, and I have a spare development and debugging laptop so lets try.
You need a spare laptop or dedicated computing environment. I would not want these tools on my main computer. They interfere with browsing, and require many editing and terminal windows. They need specific ports to be open which by nature might be a security risk. It is a very much lower risk if you use a dedicated computer for the task which only contains test code and your test environment. The laptop does not need to be particularly stellar. Im using a 7 year old ThinkPad which seems to be indestuctible and works perfectly with Ubuntu Linux.
- Linux — Ubuntu 20.04 LTS. Installed on the defaults
- Apache 2, MySQL and PHP 7.4 — The LAMP stack, installed on the defaults.
- Joomla 4 beta — A Content Management System (CMS) for the LAMP stack.
- Xdebug 3.x — Xdebug is an extension for PHP to assist with debugging and development..
- VSCodium — Community-driven, MIT-licensed, Open Source Software Binaries of VSCode.
Installing Xdebug for Joomla 4 — Step by Step
Lets skip the Linux installation. Any Linux will do fine. I just like Ubuntu, even with all its recent travails, and it supports my laptop perfectly. Install it on the defaults and that will be fine.
Installing the rest of the LAMP stack is covered in detail at HowToForge so in summary:-
- Ubuntu 20.04, optionally with a valid domain name if you plan to use Let's Encrypt SSL.
- Install Apache2, MariaDB, and PHP.
- Create a MariaDB SQL Database for Joomla.
- Download and install Joomla 4.
- Configure Apache 2 with a
VirtualHostfor Joomla and enable it.
- Optionally set up Let's Encrypt SSL.
- Run through the Joomla Installation in your browser.
- Install the sample data if you wish.
- Replace the
php.iniwith the development version for the version of php you are using.
Development version of php.ini
You'll need to use the development versions of
php.ini. Find the right php.ini-development from the branch of php project for the version you are using and download it. It will be called
php.ini-development and is set with recommended development settings. On my system the files that need to be replaced are located at
/etc/php/7.4/cli/php.ini. Simply copy the development ini over the the web server and cli production php.ini
sudo cp php.ini-development php.ini, and then restart the web server.
sudo systemctl restart apache2.
Xdebug installation wizard
Xdebug has a brilliant Installation Wizard which simplifies the process of installing it. Just paste the output from
phpinfo() from a copy and paste of the HTML, the page source or
php -i. It returns an exactly tailored set of instructions for your specific environment.
Here's my instructions (it knows I've already installed it). You should generate your own by running the wizard. They will likely be slightly different!
Example output - Ubuntu 20.04
- Xdebug installed: 3.0.2
- Server API: Command Line Interface
- Windows: no
- Zend Server: no
- PHP Version: 7.4.3
- Zend API nr: 320190902
- PHP API nr: 20190902
- Debug Build: no
- Thread Safe Build: no
- OPcache Loaded: yes
- Configuration File Path: /etc/php/7.4/cli
- Configuration File: /etc/php/7.4/cli/php.ini
- Extensions directory: /usr/lib/php/20190902
But here are the instructions anyway:
- Download xdebug-3.0.2.tgz
- Install the pre-requisites for compiling PHP extensions.
On your Ubuntu system, install them with:
apt-get install php-dev autoconf automake
- Unpack the downloaded file with
tar -xvzf xdebug-3.0.2.tgz
phpize(See the FAQ if you don't have
As part of its output it should show:
Configuring for: ... Zend Module Api No: 20190902 Zend Extension Api No: 320190902
If it does not, you are using the wrong
phpize. Please follow the FAQ entry and skip the next step.
cp modules/xdebug.so /usr/lib/php/20190902
/etc/php/7.4/cli/php.iniand change the line
zend_extension = /usr/lib/php/20190902/xdebug.so
Make sure that
zend_extension = /usr/lib/php/20190902/xdebug.sois below the line for OPcache.
- Please also update
php.inifiles in adjacent directories, as your system seems to be configured with a separate
php.inifile for the web server and command line.
These instructions were exactly correct for my system except that i have a separate
xdebug.ini which is where I need to put the
zend_extension = /usr/lib/php/20190902/xdebug.so.I do also have a separate
php.ini file for the web server and command line. This wizard simplifies the installation of Xdebug among all its dependencies.
Xdebug ini parameters
Xdebug is running now, but you need to set some parameters in
php.ini or in a separate
xdebug.ini if it exists. You can find out if xdebug is already referred to in your
php -i |grep xdebug which in my case returned
/etc/php/7.4/cli/conf.d/20-xdebug.ini telling me that there is a place to put Xdebug information. Edit the file to add more parameters to enable our IDE to communicate with it. Make sure to only have one Xdebug section and one reference to the zend_extension in the php.ini files.
zend_extension = /usr/lib/php/20190902/xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.discover_client_host = true xdebug.var_display_max_depth=10
You can check all the settings and see exactly how xdebug has been set by creating an
xdebuginfo.php much like a
<?php // Showxdebug info xdebug_info(); ?>
Doing more with Xdebug — with VSCodium
Xdebug works from a command line tool which you can download from the Xdeug website and this is good for confirming your setup and for scripting but Xdebug also supports deep integration with various editors and integrsted development environments (IDE's). I tried pretty hard to make it work with some of them including my previous favourite cross platform editors 'Sublime Text 3', and 'VIM'. I failed. I am sure it is possible to make them work but it wasn't possible for me. I noted that the Sublime Text support was based on the PHP Debug Adapter for Visual Studio Code. However I don't like proprietary licenses containing telemetary so I have always eschewed Visual Studio Code.
Turns out that the vscode source code is open source (MIT-licensed), but the product available for download (Visual Studio Code) is licensed differently and contains telemetry/tracking.
If only I didnt have to complile the open source version myself because it would be quite a distraction. Someone must have thought of that already. They have! VSCodium is a community-driven, freely-licensed binary distribution of VSCode.
Theres an open alternative to the Visual Studio Marketplace too - The Open VSX Registry offers a community driven, fully open platform for publishing VS Code extensions. The Registry is built on Eclipse Open VSX, which is an open source project hosted at the Eclipse Foundation which proclaims the benefits of being a trusted Vendor-neutral, open source operation with governance.
Our required extension PHP Debug is there and so it would seem are most all of the other existing extensions.
Installing VSCodium varies according to your platform but for Ubuntu Linux there is a repository which you can add which will allow you to keep up to date with the latest VSCodium release just using your familiar
apt update commands. See the VSCodium homepage, scroll down to Debian / Ubuntu (deb package). It was easy to install and easy to follow the extension instructions to add it to my configuration.
Conclusion - vscodium with xdebug 'just works' provided you spend some time setting it up just right.
You need to take the time set up all the right dependencies and get your port mappings right. Theres a lot of things that can go wrong and it really benefits from a dedicated Linux laptop!
How to Install Joomla with Apache2 and Let's Encrypt on Ubuntu 20.04
Edit PHP.INI File for XDebug
Branch 7.4.3 of php-src - php.ini-development