Code Debugging

Tom J Nowell edited this page Feb 4, 2018 · 18 revisions


Note: These are old instructions for VVV 1, and will not work in VVV 2+. For the latest documentation see here

VVV ships with some powerful code debugging tools just a command away. Using these tools will make you a smarter, more powerful, and better informed developer.

WordPress Debugging

Both the default and trunk versions of WordPress that ship with VVV have wp_debug turned on. If you installed your own version, ensure this is the case. Find wp-config.php. You need a line somewhere in the file that says the following:

define( 'WP_DEBUG', true );

If this is new to you, it's suggested that you view your site now. If there are PHP notices or errors, they will be output to the screen.

Other, standard methods of debugging

Var_dump Debugging uses var_dump($var); die(); to inspect variables at different points in the code. This is a sledgehammer, but is effective. It will show you variable information, then kill all script execution past that point. Without xDebug, it's pretty ugly, so you might wrap it with <pre></pre>

In the plugin repository is the Debug Bar and Debug Bar Extender. The latter has some functions that allow you to more elegantly output variables to the debug bar. There are more plugins available for the debug bar to help diagnose specific issues: Cron, Rewrites, and Post Meta.

If you are getting a blank screen, or maybe have PHP errors, you can view the PHP errors logs on your vagrant at /srv/log/php_errors.log. To do so connect to your vagrant using vagrant ssh and then view your logs using sudo tail -f /srv/log/php_errors.log. If you have defined WP_DEBUG to true in your site's wp-config.php, the logs will instead be in the site's wp-content folder, at wp-content/debug.log.

Finally, when you've just about given up hope, Rubber Duck Debugging is a last resort. Turn to the rubber duck you keep on your desk (you do keep a rubber ducky on your desk, right?) and explain the problem. By the end, you may have an answer.

Meet xDebug

Did I say last resort? Clearly I meant it's the last resort if you don't know about xDebug. This fantastic extention to PHP is pre-compiled in VVV and is waiting to be turned on.

Turning on xDebug

  1. Open a console window, and cd into your vagrant directory.
  2. SSH into vagrant: vagrant ssh.
  3. Turn on xDebug: xdebug_on

Gif showing xdebug being turned on and off using the above steps.

xDebug configuration will be added to your php.ini and php5-fpm will be restarted. You can modify your version of xdebug by editing /config/php5-fpm-config/xdebug.ini and restarting php5-fpm.

Hint: a convenient way to restart php5-fpm is to run xdebug_on or xdebug_off. You can also run sudo service php5-fpm restart

Prettier errors

xDebug wraps PHP errors in an HTML table with some rather striking colors that are sure to get your attention. Oh, and a very useful stack trace.

Image comparing the display of PHP errors and warnings with xdebug on and off

Prettier var_dumps

Var_dump() is now formatted and syntax highlighted.

Image comparing the display of var_dump() with xdebug on and off

Step-through, Remote Debugging

xDebug also provides a powerful tool not available without it: remote debugging. Chiefly, this allows you to pause PHP execution and run through the stack one function at a time, inspect values, change variables, evaluate functions at a specific point during execution. Basically you see precisely what your code is doing when it runs.

Setting up remote debugging

Once xDebug is turned on, the only thing needing further configuration is your client. Most IDE's will have support for remote debugging and there are some standalone clients. The xDebug Documentation has a full list

View a screencast of setting up path mappings in PHPStorm

Our xDebug configuration is set to automatically start on every request and attempt to connect to a client on the default port 9000.

Because VVV uses mapped folders, the www directory as it appears to PHP is in /srv/www. It may be in a completely different place on your local machine. Therefore, you'll likely need to specify path mappings to relate the two.

Note: The above links are the result of searching, the only one that has been verified accurate is PHPStorm. Unfortunately, it's also the most confusing. Pull requests with more detailed walkthroughs are welcome.


So thanks to all these fancy debugging tools your script is running. But how well is it running? VVV is now shipping with profiling tools.

Basic profiling, it should be noted, can be accomplished using the Debug Bar Extender profiling tools. For more accurate, more robust, and more awesome profiling, keep reading.

Once you turn on xdebug (remember: xdebug_on while SSH'd into Vagrant), you'll have the profiler immediately available. Make any URL request and append ?XDEBUG_PROFILE and a cachegrind file will be generated.

Cachegrind files can be evaluated by a few external programs, but we've built in Webgrind to VVV. On a default installation, visit

Try this now

If you have a default VVV box installed per the instructions

  1. If xDebug isn't turned on (or you aren't sure), follow the instructions above
  2. Visit http://local.wordpress-trunk.test/?XDEBUG_PROFILE. This will generate a cachegrind file in /tmp
  3. Go to Webgrind at http://vvv.test/webgrind
  4. Click "update" in the upper right. The Auto (newest) drop down will allow you to select from older cachegrind files.

Interpreting a cachegrind file

WebGrind will show you (by default) the top 90% of functions, methods, and includes of the latest cachegrind file by percent (of time the total execution time).


  • Type of item: function, method, or include
  • Function name
  • Jump to code button
  • Invocation Count: how many times this item is run
  • Self Cost: cost of this item, but not anything it calls
  • Total Cost: cost of this item, including what it calls

Screenshot of webgrind's cachegrid analysis

Type of Item

  • Internal (PHP) function — blue
  • Included or Required file — grey
  • class methods — green
  • regular, or procedural, functions — orange

Function name

Clicking on a function or item name will show you all of the functions and methods that it calls and anything that it is called from. This allows you to take any function and walk up or down in the execution tree to find the real bottleneck.

Jump to code button

This amazing little button will jump to a syntax-highlighted, line-numbered HTML page and show you the function, method, or include in context.

Invocation Count

See exactly how many times apply_filters() is called. Hint: lots and lots.

Self Cost

Depending on what you selected in the upper right—percent, miliseconds, or microseconds—the units will differ, but the meaning is the same. This gives the relative weight of this function, method, or include by itself. That is, it's weight without considering all of the functions, methods, or includes that it calls.

Total Cost

Conversely, total cost counts everything that a function, method, or include calls. "{Main}"" should always have a total cost of 100%, since it will include the cost of every function, method, or include that runs.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.