We're live-coding on Twitch! Join us!
Debugging PHP in Visual Studio Code

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’);

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


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