Setting up PhpStorm, Xdebug to work with WordPress PHPUnit Testing

I’m a huge fan of using Xdebug and recently I ran into some issues with writing PHPUnit tests for my WordPress theme.  It took me longer to debug than usual because I couldn’t get PhpStorm to stop at my debug breakpoint.  Actually, I couldn’t get Xdebug to work at all — if I had Xdebug enabled, PHPUnit wouldn’t even run — it would just hang.

I tracked the issue down to this line in tests/bootstrap.php

system( WP_PHP_BINARY . ' ' . escapeshellarg( dirname( __FILE__ ) . '/install.php' ) . ' ' . escapeshellarg( $config_file_path ) . ' ' . $multisite );

A Google search brought me to this closed WP Core trac ticket.

That ticket has a helpful suggestion, which I hope to immortalize here, as it is the solution to this problem.

Max. Simultaneous Connections Setting

The solution is to change the Max. simultaneous connections setting, which can be found in Default preferences -> Languages and Frameworks -> PHP -> Debug.

Increase the phpStorm max connections setting to get xdebug to work.

“Configure Php Include Paths”

The default setting is 1, change it to 3 or more!


If that doesn’t solve your problem instantly, then I shall ask, did you Configure php include paths so that the phpunit files are included?  Also, depending on your development environment, you may need to set up path mappings so that PhpStorm knows how the server files are mapped to your local ones.

Happy testing!

Debugging WordPress with PhpStorm’s Console Window and xDebug

As a backend WordPress developer, I use PhpStorm to help me develop and debug.  If you’re not familiar with it, PhpStorm is an IDE, so it combines all of the things that I need to do as a programmer into one interface — think code editor plus a debugging interface, git integration, terminal window, etc.

I have fond memories of discovering PhpStorm.   I developed many of my basic programming skills while working in Java.  I used the Eclipse IDE for Java and when I switched to Php, I searched for something equally helpful.  I found PhpStorm.

It turned what I saw as a confusing mess of php files into something I could explore, understand, and build upon.

And yet, the amount of tools available in PhpStorm can be intimidating.  So, unfortunately, I’ve spent the last few years completely ignoring the Console window.  My mistake!

First, this assumes that you’ve got xdebug enabled and configured within PhpStorm properly.  I’ll admit that it can take several hours to get xdebug set up, especially if you’re unfamiliar with how it all works and don’t have a coworker to walk you through it.  But those several hours of persistence will pay off handsomely.

When tackling an issue, I often set a debug point before the code I’m about to examine or change, and then a debug point afterwards.

This way I can step through my code, inspect the variables, and double-check that it’s doing exactly what I want it to be doing.  I find that’s a good way to really understand the code, which is critical to changing the code correctly and not creating new bugs.  Writing unit tests is even a better idea than just inspecting variable values, but not all situations lend themselves to that.

So I usually double-check my work by inspecting variable values.

In PhpStorm, if you have the debug window open, you should see a “Console” tab at the top of that.  If you switch to that, you’ll see a command prompt, at which we can run code within the context of our program.  So when the program stops at the breakpoint, you can switch to the console window and start typing commands.  Let’s try a few.

How did we get here?  Use wp_debug_backtrace_summary()

wp_debug_backtrace_summary will print a comma-separated list of the functions that have been called to get the the current code point.

Here’s a screenshot of me debugging a filter called by Jetpack.  If you’ve ever wondered about the context of when a filter or action is being called, this is a helpful function.  As you can see in my screenshot, wp_debug_backtrace_summary reveals that wp_head was called, so I’m in code that’s running within the head of the website.

This is also helpful when debugging and you’ve realized that you’ve set your breakpoint too late in the execution.  You can look at the list of functions already called and set your breakpoint in one of those.

What are we working with? Use get_post() or get_term()

Is your code trying to manipulate a post object?  Are you trying to change something on a save_post hook?  There’s lots of scenarios where you may be wondering why some code isn’t working.  A common issue is that we’re trying to do something at the wrong time in WordPress execution.  An example would be trying to use some post meta before it’s been saved.

If you’re working with a term object, you can use get_term() to inspect the term object as well.

In the above screenshot, the code execution has stopped at my breakpoint (line that ends in 27 above).  PhpStorm has highlighted the line that I’m on.  I blurred out the function name for privacy, but that’s where I am.  It’s about to call that function and it will pass it the $id, which is 36459.  I know that’s a post ID, and it would be super helpful to know what kind of post it is here, so I ran a get_post() command, which returns the WP_Post object. In this case it’s a guest-author post.

So, an awesome debugging process is to get the data from the database and display it, to make sure it’s what we expect.

Did you write a new function?  Try it out with different parameters.

After writing a new function, we have to check if it works correctly.  The best way to check this would be unit testing, and the most time consuming way would be to reload the web page or multiple pages to check that it gives the expected result. Reloading pages is super time consuming and can be an inaccurate way to measure one function’s correctness.

A quick way is to manually run the function with different inputs, and check the output in the console window.  Here’s an example of me doing that — as you can see, the function here can return a DateTime object or a Unix timestamp, depending on the input.  This is good demo of using this console in an interactive way.


What else is awesome to try in the console?

Do you use the console and have any helpful tips?

It’s also a handy place to just evaluate code to check its correctness.  Next time you’re doing code review and aren’t sure if a WordPress function is being called correctly, pop it into the console.


How to Solve Software Bugs with Wrappers

I’ve taken an interest in improving legacy software.  I use the term legacy broadly here, to refer to software that does something in an outdated way.

It is possible to spend many hours and days trying to figure out WHY a bug occurs.  Lately, I’ve decided that the fine detail of why the bug occurs doesn’t matter in some cases.  That’s right, it doesn’t matter.

All you need is a deep understanding of the problem.

If the problem is that the data going into a function is good but the data coming out of that function is bad, then you can simply replace that function with your own function.

You just have to make sure that you perform all of the necessary actions of that function, so that you don’t mess up any other aspects of the program by accident.  THAT is the tricky part!

Or, your wrapper can just do the really important buggy part of that function and then you might call the original function afterwards, so that your bug fix only adds something extra.  Performing careful code changes in a complex system can be similar to surgery.  You don’t want to excise too much, as that could cause other, new bugs.

When should you use a wrapper?

  1. When you can’t change the buggy code because it’s outside of code that you control.  For example, the bug may be in the framework, NPM package, WordPress core or third-party plugin, other library or dependency, or, operating system, browser, etc.
  2. When it would take too much development time to rewrite the code in question.  Everyone loves a quick fix.

I love elegant software design, but at the same time I’m happy to have a fix that works any day of the week.

If you’re interested in learning more about software design, you may enjoy Head First Design Patterns.

Happy coding!