Do you Xdebug your PHP code?

5 min readDec 12, 2020

Debugging the code is an integral part of our work and If I say as a developer we spend more than half of the development time on debugging, it wont be too wrong.

Well, the typical approach of debugging many of developers choose (Including me 😅) is to add incremental visual breakpoints in the code flow (with var_dump(), exit(), dd() ) and execute the flow to check if any of them ever hits. I myself did this for too long until I realized thought it was quick and simple, It was not practical for complex cases and that’s the time I had switched to something better ie. xdebug

Ever since, I have setup my work flow with xdebug it has not only saved me some extra time but also improved the overall debugging experience and quality of my workflow and now there is no turning back! Ok so enough of story and lets get into the actual discussion.

Setup :

Install Xdebug :

Installing and setting up xdebug on your machine is nothing more that installing an application for your system. The official Xdebug page here mentions all the details about platform specific installation details.

For the simplicity purpose I will consider the windows and ubuntu(WSL) platform with VScode as editor.

For windows based system with setup such as XAMP/WAMP :

Go to command line and run php -v and copy the output.
visit the url https://xdebug.org/wizard and paste the output you copied. the site will give you the correct version of xdebug you need to install.

copy the downloded .dll file and paste it into the C:\xampp7\php\ext directory.

Installing on Linux based system (WSL/Ubuntu in my case) :

To install Xdebug on Linux based system, we can use the default package manager. just run the below command :

> sudo apt-get install php-xdebug// Note : when you have multiple php version installed you will need to specify the php version for which you need to install php> sudo apt-get install php7.4-xdebug

Note : please find the correct installation command based on your system here https://xdebug.org/docs/install#linux

Pro Tip : If you know your correct configuration, you can directly visit the URL (https://xdebug.org/download ) and download the required binaries for your system.

Configure Xdebug:

So far we have only downloaded the required binaries and we need to tell PHP about the Xdebug for using it. This can be done by simply editing the default php configuration file i.e. php.ini or if you have specific .ini loaded separately then updating that file.

For windows based system with XAMP/WAMP :

Locate the php.ini file which is typically located under folder C:\xampp\php
Edit the file and add the following lines at the end of file.

[XDebug]zend_extension = C:\xampp\php\ext\php_xdebug-2.9.6-7.3-vc15-x86_64.dll#xdebug 2xdebug.remote_enable=1
xdebug.default_enable=0
xdebug.profiler_enable=0
xdebug.auto_trace=0
xdebug.coverage_enable=0
xdebug.remote_autostart = 1
xdebug.remote_port=9000
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_pack=1
xdebug.idekey=XDEBUG_ECLIPSE
xdebug.var_display_max_depth = 10#xdebug 3
xdebug.mode=debug
xdebug.start_with_request = yes#to use default_enable set xdebug.mode=develop
#to use profiler_enable set xdebug.mode=profile
#to use auto_traceset xdebug.mode=trace with xdebug.start_with_request=yes
#to use coverage_enable set xdebug.mode=coveragexdebug.client_port = 9003 #9003 is default port now!
xdebug.client_host=127.0.0.1
xdebug.discover_client_host=1
xdebug.var_display_max_depth = 10

save the file and restart the WAMP/XAMP server for changes to take effect.

Note : The name and path of .dll file may be different your case so, please verify that at your end.

For Linux based system (Ubuntu/WSL)

Locate the php.ini file (or *-xdebug.ini if any) and append the following lines to the end of the file.

zend_extension=xdebug.so
#xdebug 2xdebug.remote_enable=1
xdebug.default_enable=0
xdebug.profiler_enable=0
xdebug.auto_trace=0
xdebug.coverage_enable=0
xdebug.remote_autostart = 1
xdebug.remote_port=9000
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1
xdebug.idekey=XDEBUG_ECLIPSE
xdebug.var_display_max_depth = 10#xdebug 3
xdebug.mode=debug
xdebug.start_with_request = yes#to use default_enable set xdebug.mode=develop
#to use profiler_enable set xdebug.mode=profile
#to use auto_traceset xdebug.mode=trace with xdebug.start_with_request=yes
#to use coverage_enable set xdebug.mode=coveragexdebug.client_port = 9003 #9003 is default port now!
xdebug.client_host=127.0.0.1
xdebug.discover_client_host=1
xdebug.var_display_max_depth = 10

Save the file and restart the http server (apache)

Note : The key zend_extension specify the name of the default socket file if you face any issue about connecting the socket file please review the socket file permissions at path /usr/lib/php/<randomdate>/xdebug.so

IMP : The above config options are just basic one to get you started. The Xdebug 3 and xdebug 2 have many configuration changes available/updated/modified so, kindly review the official upgrade guide here before you make any changes to your configuration.

eg. To debug the command line code, you will need set
export XDEBUG_SESSION=<yourkey> for xdebugx3 the xdebug.ide option.

Configure VSCODE :

Configuring the vscode for xdebug is just about installing an extension

Open vscode and click on CTRL + shift + x to open the extension window or simply click on view -> extensions
Search for “PHP debug” and click on install

Configure debug configuration :
To debug the code we need to do some additional settings that will allow the vscode to communicate with xdebug.

Click on run -> add configuration and past/edit the following JSON in the opened lauch.json file.

"configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003
        }
    ]

Save the file and you are all set.

Update : 1-July-2021

If you are debugging with VSCode Remote (WLS) you will need to add following mappings in your configuration

{
    "name": "Listen for XDebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": {
       //eg remote path /home/rohits/project
        "remote-path-to-project": "${workspaceFolder}/",
     }
}

Debug the code :

Open the file you want to debug and add the breakpoint to the section you wish to debug now click on F5 button or click on run -> Start debugging
Execute the code you have added breakpoint to and If you followed all steps correctly and if everything works well for you, you should be able to see the breakpoint hit with vscode indicating the same.

I hope this article will help you in some way and thanks for your time!

Happy debugging! 🐜 😃😃

Update: 14-dec-2020 xdebug configuration options as per xdebug 2 and xdebug 3 when Derick Rethans himself identified some of mine silly mistakes here! 😅