Debugging PHP in Visual Studio Code

If you are a PHP developer who has worked with Microsoft technologies in the past, you would certainly
miss its Visual Studio editor with full debug support: F5 to run the debugger, F6 to step next, F7 to step into,
F8 to step out, etc. It simply works like magic.

Do you miss it? I certainly do.

The good news is that there are a few open source tools out there that can give PHP developers the same
debugging experience.

#A Breif History of PHP Debugging

Whenever we talk about PHP debugging, one thing always comes to mind: XDebug. I would not dream of
coding anything in PHP without it. But it was a totally different story before.

Remember PHP var_dump()? It was the only tool of the trade when it came to debugging PHP back in the
day.

The first thing we did was turn on display_errors. We would do this either in the php.ini file or at the
beginning of the code:

ini_set(‘display_errors’, ‘On’);
error_reporting(E_ALL);

We would also have certainly relied on the handy dandy echo command to watch any variable values, and
then diligently remove or comment them out once we were done. This is pretty much how all PHP
applications were troubleshooted during the pre-xdebug days.

Enter XDebug.

#What is XDebug
XDebug is a PHP extension that provides debugging capabilities for programming IDE. It was first released in
May 2002 by Derick Rethans. At the time of this writing, the latest version( 2.5.3.) of XDebug has become the
de facto standard as it is the only debugging tool in existence for PHP. Thank you, Derick! My life has never
been the same.

Xdebug can do:

Set/Remove breakpoints
Perform an automatic stack trace
Set a manual variable watch
Enable function call logging
Enable profiling
Allow remote debugging

#How to Install XDebug

XDebug is essentially a file (an .so file on Linux and a .dll on Windows) that you must install on your server.

Before the install, I recommend to start with the XDebug installation wizard. It does an excellent job of
analyzing your PHP environment, then gives you tailored installation instructions.

To configure PHP to use XDebug, add the line zend_extension=path/to/xdebug to your php.ini.

Finally, to enable debugging, enter the following in your php.ini in [XDebug] :

xdebug.remote_enable = 1
xdebug.remote_autostart = 1

Install XDebug From Your Mac OSX

If you are on a Mac, my preferred way is to use Homebrew

brew install <php‐version>‐xdebug

eg.

brew install php56‐xdebug

I'm going to share a little trick I use to install XDebug on a Mac. Here’s the one liner in OSX that enables the
PHP XDebug extension.

sudo sh ‐c 'echo zend_extension=$(find /usr/lib/php/extensions ‐name "xdebug.so") >> $(php ‐qr

"echo php_ini_loaded_file();") && apachectl restart

This command does the following :

1. Finds the native Xdebug extension that comes with Xcode

2. Asks php which config file is loaded
3. Adds the Xdebug extension path to the config file
4. Restarts Apache.

Read the official XDebug installation guide: https://xdebug.org/docs/install

Finally, verify your installation by checking your phpinfo() output to see if there’s an XDebug section.
#XDebug in Visual Studio Code
Visual Studio Code is a free, open source, cross-platform lightweight code editor from the software giant. It
is available for Windows, Linux and OS X. You can download it here.

Now that we should have already installed XDebug on our server, we need to get the debug client installed
in VS Code so we can set the breakpoints in the code that will be hit when PHP is processing the request. To
do this, we need to get the "PHP Debug" Extension from VS Code. An easier way is to go to the Extensions
tab, and search for "PHP Debug", and then click Install.

Once the installation is complete, be sure to restart VS Code before you start using it.
To add a breakpoint, click to the left of the line number or, once you have selected a line, press F9 on your
keyboard.

Then click the Debug icon on the left-side menu.

Be sure the "Listen to XDebug" option in the configuration dropdown is selected.

Finally click the green "Play" icon or press F5 on the keyboard to start the debugging.

Now, open your web browser and visit the webpage where we set the breakpoints earlier. If everything has
been set up correctly, as soon as the program hits the first breakpoint, you should be immediately switched
back to VS Code.
Now you can use the buttons in the debug bar to proceed with debugging. Learn to use keyboard
shortcuts! The highlighted yellow line indicates where execution stopped in our PHP script.

Pay close attention to the VARIABLES and CALL STACK on the left-hand pane. They are like having a dynamic
PHP var_dump() command at your disposal.

For the demo, I set a single breakpoint on the following line,

$dg = new C_DataGrid("SELECT * FROM orders", "orderNumber", "orders");

In reality, you can set as many breakpoints as you need. To STEP OVER to the next breakpoint, press F10
on your keyboard; to STEP INTO the current line breakpoint, press F11.

#Final Thoughts
Visual Studio Code provides great PHP language support right out of the box. Debugging PHP with VS Code
is surprisingly smooth. My first time debugging was like debugging C# in the good old days. Step in, out,
over, watch etc., all work like charm!

One of the things I’ve learned is that where you put breakpoints for scripts inside MVC such as Laravel can
be tricky. In my experience the best place to put breakpoints is inside the model where all database actions
take place. Step-in doesn’t always work when debugging in MVC because of the routing.

What is your take on Debugging PHP? Please share!

Richard is a senior PHP developer at phpgrid.com