Installing PHP Xdebug on Ubuntu can be a useful tool for PHP developers who want to debug their code in real-time. Xdebug is a popular PHP extension that provides debugging and profiling capabilities for PHP code. By installing Xdebug, developers can step through their PHP code line-by-line, set breakpoints, and inspect variables and function calls, among other features.
However, installing Xdebug on Ubuntu can be a complex process, especially for those who are new to PHP development or the Ubuntu operating system. In this guide, we will provide step-by-step instructions on how to install and configure Xdebug on Ubuntu, as well as tips for troubleshooting common issues that may arise during the installation process. By following these instructions, you can easily install and use Xdebug to improve your PHP development workflow.
What is Xdebug?
Xdebug is a debugging tool used in the PHP programming language. xdebug is used to monitor the runtime behavior of PHP code, identify errors and analyze the performance of the code. Xdebug uses the DBGp debug protocol.
Xdebug offers developers the following features;
- Displaying variable values at code runtime
- Code flow monitoring and step-by-step execution
- Catch and view errors during code execution
- Used to collect profile data and analyze the performance of the code
Pre-requisites
Before installing PHP Xdebug on Ubuntu, you should have a few pre-requisites installed on your system:
PHP:
Xdebug is a PHP extension, so you need to have PHP installed on your system before installing Xdebug. You can install PHP on Ubuntu using the following command:
sudo apt-get install php
Web server:
You also need to have a web server installed on your Ubuntu system to run PHP scripts. Apache and Nginx are two popular web servers that you can use. You can install Apache or Nginx on Ubuntu using the following commands:
sudo apt-get install apache2 sudo apt-get install nginx
PHP development tools:
To make the most of Xdebug, it is recommended to have some PHP development tools installed on your system, such as an Integrated Development Environment (IDE) or a text editor with PHP debugging capabilities. Examples of such tools are PHPStorm, VS Code, Eclipse, and NetBeans.
Command-line interface (CLI):
If you want to use Xdebug with the PHP command-line interface (CLI), you need to have the CLI version of PHP installed on your system. You can install the PHP CLI on Ubuntu using the following command:
sudo apt-get install php-cli
By ensuring that you have these pre-requisites installed on your Ubuntu system, you can proceed with installing PHP Xdebug and start debugging your PHP code.
Different methods to install php Xdebug on Ubuntu
The xdebug package is available in the Ubuntu repositories. You can install it easily. If you want a newer version, you can install it from the source code.
Method-1: Install From Repository
Update the package list before starting the installation:
$ sudo apt update -y
Then you can install xdebug according to your php version. If you are not using a specific version, install like this:
$ sudo apt install php-xdebug -y
If you want to install xdebug according to the php version installed on your system, first check the php version:
$ php -v
PHP 8.1.2-1ubuntu2.11 (cli) (built: Feb 22 2023 22:56:18) (NTS)
...
then install xdebug package for this version:
$ sudo apt install php8.1-xdebug -y
Xdebug has been successfully installed, you can check Xdebug by entering the following command:
$ php -m | grep xdebug
xdebug
This command will list installed PHP modules and you can check if Xdebug is also listed.
Method-2: Install From Source Code
For installation from source code, you must first install the following packages:
apt install php-dev wget -y
The source code can be downloaded from the Xdebug official site.
Or pull the source code with wget:
$ wget https://xdebug.org/files/xdebug-3.2.0.tgz
--2023-03-16 22:50:06-- https://xdebug.org/files/xdebug-3.2.0.tgz
Resolving xdebug.org (xdebug.org)... 82.113.146.227
Connecting to xdebug.org (xdebug.org)|82.113.146.227|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 245775 (240K) [application/x-gtar-compressed]
Saving to: ‘xdebug-3.2.0.tgz’
xdebug-3.2.0.tgz 100%[=============>] 240,01K 468KB/s in 0,5s
2023-03-16 22:50:07 (468 KB/s) - ‘xdebug-3.2.0.tgz’ saved [245775/245775]
Unzip the downloaded compressed file:
$ tar -xzf xdebug-3.2.0.tgz
Then go to the xdebug directory:
$ cd xdebug-3.2.0/
Make sure you are using phpize for the PHP version you want to use xdebug with.
$ phpize
Configuring for:
PHP Api Version: 20210902
Zend Module Api No: 20210902
Zend Extension Api No: 420210902
configure.ac:22: warning: $as_echo is obsolete; use AS_ECHO(["message"]) instead
build/php.m4:2111: PHP_CONFIG_NICE is expanded from...
configure.ac:22: the top level
configure.ac:165: warning: The macro `AC_PROG_LIBTOOL' is obsolete.
configure.ac:165: You should run autoupdate.
build/libtool.m4:99: AC_PROG_LIBTOOL is expanded from...
configure.ac:165: the top level
Start Configure:
$ ./configure --enable-xdebug
Then run make:
$ make
Then run make install:
$ sudo make install
After installation, configure the php.ini file:
$ sudo vi /etc/php/8.1/cli/php.ini
Write the following line in this file:
zend_extension=xdebug
You can see the Xdebug version in the php -v output:
foc@ubuntu22desktop:~/xdebug-3.2.0$ php -v
Cannot load Xdebug - it was already loaded
PHP 8.1.2-1ubuntu2.11 (cli) (built: Feb 22 2023 22:56:18) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
with Xdebug v3.2.0, Copyright (c) 2002-2022, by Derick Rethans
with Zend OPcache v8.1.2-1ubuntu2.11, Copyright (c), by Zend Technologies
Or:
foc@ubuntu22desktop:/$ php8.1 -v
Cannot load Xdebug - it was already loaded
PHP 8.1.2-1ubuntu2.11 (cli) (built: Feb 22 2023 22:56:18) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
with Xdebug v3.2.0, Copyright (c) 2002-2022, by Derick Rethans
with Zend OPcache v8.1.2-1ubuntu2.11, Copyright (c), by Zend Technologies
If xdebug does not appear in this list, or if you receive a warning from PHP that an xdebug.so file or similar is not found, you may need to use the full path instead of zend_extension=xdebug. First find where xdebug.so is:
foc@ubuntu22desktop:/$ sudo find / -iname xdebug.so
...
/usr/lib/php/20210902/xdebug.so
...
Then define the xdebug library address found in the above output into the php.ini file.
Configure Xdebug
Once Xdebug is installed, you need to configure it for your PHP environment. Open the Xdebug configuration file using the following command:
sudo nano /etc/php/<your_php_version>/mods-available/xdebug.ini
Replace <your_php_version> with your installed PHP version, for example, 7.4.
Add the following configuration settings to the xdebug.ini file:
zend_extension=xdebug.so xdebug.remote_enable=1 xdebug.remote_autostart=1
These settings will enable remote debugging and automatically start the debugger when a PHP script is executed.
After configuring Xdebug, you need to restart the PHP service to apply the changes. You can restart the PHP service using the following command:
sudo systemctl restart php<your_php_version>-fpm.service
Replace <your_php_version> with your installed PHP version, for example, 7.4.
Verify the installation
To verify that Xdebug is installed and configured correctly, create a PHP script with the following code:
<?php phpinfo(); ?>
Run the PHP script using your web server and open it in a web browser. You should see the Xdebug section in the PHP information page, indicating that Xdebug is installed and working.
Summary
In this article, we have covered how to install PHP Xdebug on Ubuntu, along with the necessary pre-requisites required for a successful installation. We have discussed two different methods for installing Xdebug: installing from the Ubuntu repository and installing from source code. Additionally, we have provided step-by-step instructions for configuring Xdebug, including enabling remote debugging and starting the debugger automatically when a PHP script is executed. Finally, we have discussed how to verify that Xdebug is installed and working correctly by checking the PHP information page. By following these instructions, developers can easily install and use Xdebug to improve their PHP development workflow on Ubuntu.
References
xdebug.org - Xdebug Installation
stackoverflow.com - How to install Xdebug on Ubuntu?
