Xdebug Logo by Muglug, CC BY-SA 4.0 , via Wikimedia Commons
Xdebug Logo by Muglug, CC BY-SA 4.0 , via Wikimedia Commons


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.

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:-

  1. Ubuntu 20.04, optionally with a valid domain name if you plan to use Let's Encrypt SSL.
  2. Install Apache2, MariaDB, and PHP.
  3. Create a MariaDB SQL Database for Joomla.
  4. Download and install Joomla 4.
  5. Configure Apache 2 with a VirtualHost for Joomla and enable it.
  6. Optionally set up Let's Encrypt SSL.
  7. Run through the Joomla Installation in your browser.
  8. Install the sample data if you wish.
  9. 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:

  1. Download xdebug-3.0.2.tgz
  2. Install the pre-requisites for compiling PHP extensions.
    On your Ubuntu system, install them with: apt-get install php-dev autoconf automake
  3. Unpack the downloaded file with tar -xvzf xdebug-3.0.2.tgz
  4. Run: cd xdebug-3.0.2
  5. Run: phpize (See the FAQ if you don't have phpize).

    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.

  6. Run: ./configure
  7. Run: make
  8. Run: cp modules/ /usr/lib/php/20190902
  9. Update /etc/php/7.4/cli/php.ini and change the line
    zend_extension = /usr/lib/php/20190902/
    Make sure that zend_extension = /usr/lib/php/20190902/ is below the line for OPcache.
  10. Please also update php.ini files in adjacent directories, as your system seems to be configured with a separate php.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/ 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.iniusing 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.discover_client_host = true


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


	// Showxdebug info

xdebuginfo - screenshot
Xdebug - xdebuginfo.php

Doing more with Xdebug — with VSCodium

VSCodium - screenshot
VScodium - Ubuntu 20.04

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.

VSCodium - screenshot
VScodium with PHP Debug - Ubuntu 20.04

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