Debugging PHP based applications running on a server is a little tricky. Sophisticated IDEs for PHP are available to buy in the market. If you are frugal like I am, then your options are limited. Open Source community provides pieces to enable debugging web based PHP applications. However, stitching up these pieces together to set up an end to end environment is usually a challenge for junior developers.
Junior developers usually are not very well versed in setting up server components like apache and PHP. They consider the server as a black box, even boiling down to a single server software in the form of WAMP/XAMPP server. Setting up PHP debugger involves installing several pieces of software and configuring PHP and other environments, further making it non-trivial for a large number of developers.
This guide walks you through setting up each piece to enable debugging web applications built on PHP. Note that there are several ways to achieve what is done here. The intent here is to simplify set-up to get going with quick steps. The steps should work for development machines, where entire stack may be on just one machine. It should also work if individual layers of stack are spread over different machines, so long as they are all in the same network. Remote debugging for environments that span network boundaries is also possible, however, we’ll leave it for some other time.
Installation
In this guide, we will use following software to set up end to end environment to debug PHP applications
- Microsoft Visual Studio Code – This is a very light weight editor from Microsoft. Although it is fairly new, I am impressed at the capabilities it has already amassed. Best part – it is available for different platforms.
Download and install VS Code from here: https://code.visualstudio.com
VS Code is open source and can be found on github here: https://github.com/Microsoft/vscode
- PHP debug extension for VS Code – VS Code comes with a plethora of extensions that add capabilities to it. We will use the PHP-Debug extension by Felix Becker.
Open VS Code, press CTRL+P and then type: ext install php-debug
PHP-Debug extension is open source and can be found on github here:https://github.com/felixfbecker/vscode-php-debug
- XDebug – This is the core of the debugger. It actually is a PHP extension that implements the DBGp protocol.
Download extension customized for your machine, from here:https://xdebug.org/wizard.php
The link also gives clear instructions about how to install the extension.
XDebug is open source and code is available here : https://github.com/xdebug/xdebug
- Chrome XDebug Helper – this is a Chrome extension that enables debugger remotely, based on query parameters. It is also possible to always keep the debugger on, using PHP.ini config options.
Follow installation steps here: https://github.com/mac-cain13/xdebug-helper-for-chrome
End to End
XDebug site has very good documentation on how the final end to end setup will look like. Check it out here: https://xdebug.org/docs/remote, particularly the gifs showing steps and flow.
In short, the remote debugging works on a client server model. Your IDE (VSCode here) is the server. by default, it will listen on port 9000. XDebug PHP extension acts as a client. The extension can be invoked based on a variety of configuration options. Once invoked, it will connect to the server and relay all the debug information. In VS Code, you may also step through the code line by line and the client and server will follow DGBp protocol to enable remote debugging.
Configuration
- Configuring XDebug – Xdebug comes with several configuration options to suit your debugging needs. you can review the options at XDebug website. They need to be configured in your php.ini file. Of particular interest for remote debugging are following options:
xdebug.default_enable=1
Xdebug.remote_enable=1
Xdebug.remote_host=localhost (or the IP of the machine where VSCode is running)
Xdebug.remote_port=9000
xdebug.remote_autostart=1
remote_autostart will debug every http request. There are other ways to control on which requests the debugger will be invoked. This is by far the easiest to begin with. If you want to selectively debug requests, you can use the XDebug Helper Chrome extension (described below)
- In VSCode, go to “File”à”Preferences”à”User Settings”. On the right-hand side of split window, add path for php.exe file:
“php.validate.executablePath”: “c:\\xampp\\php\\php.exe”,
- Open VS Code, click on the debug button. A blue button with title “Add Configuration” shows up on the bottom right hand side. Click on it and VSCode will add default configuration for XDebug. Accept it.
Showtime
- Open your code in VSCode and set breakpoints
- Fire up chrome. You should see ‘Xdebug Helper’ extension icon. Click on it and select Debug. This step is necessary only if you have set remote_autostart=0 in php.ini file.
- fire your query and voila! You should see the code paused in your VS Code breakpoint.
Happy Debugging!!