Xdebug
Xdebug is an extension for PHP to assist with debugging and development. With great power comes great responsibility. Don't leave it enabled in production.
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.
Pre requisites
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.
Contents
- Xdebug
- Pre requisites
- Installing Xdebug for Joomla 4 — Step by Step
- Let's Encrypt
- Development version of php.ini
- Xdebug installation wizard
- Xdebug ini parameters
- xdebuginfo.php
- Doing more with Xdebug — with VSCodium
- Conclusion - vscodium with xdebug 'just works' provided you spend some time setting it up just right.
See also:
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
VirtualHost
for 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.ini
with the development version for the version of php you are using.
Let's Encrypt
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/apache2/php.ini
and /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!
- 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
You're already running the latest Xdebug version
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
- Run:
cd xdebug-3.0.2
-
Run:
phpize
(See the FAQ if you don't havephpize
).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. - Run:
./configure
- Run:
make
- Run:
cp modules/xdebug.so /usr/lib/php/20190902
- Update
/etc/php/7.4/cli/php.ini
and change the linezend_extension = /usr/lib/php/20190902/xdebug.so
Make sure thatzend_extension = /usr/lib/php/20190902/xdebug.so
is below the line for OPcache. - Please also update
php.ini
files in adjacent directories, as your system seems to be configured with a separatephp.ini
file 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.ini
using 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
xdebuginfo.php
You can check all the settings and see exactly how xdebug has been set by creating an xdebuginfo.php
much like a phpinfo.php
page
<?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!
See also:
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