Debugging JavaScript and PHP at the same time with PhpStorm

Since I started with Delicious Brains last July, I’ve become a big fan of PhpStorm. It really is the bee’s knees. I won’t go over the full list of features, but some of the things I find helpful daily are:

  • Cmd+clicking into method definitions
  • VCS integration and color highlighting of code changes
  • Code bookmarks
  • And of course, Xdebug integration

In this post I want to expand on what Iain already covered with PhpStorm and Xdebug and show you how to level up your JavaScript debugging skills with PhpStorm. Let’s get to it!

Why Use the PhpStorm Debugger?

Have you ever found yourself with a complex JavaScript file or method and you needed to know the value of a variable at some point during the script execution? I know I have, especially when ‘grokking‘ a new codebase or function. What I would normally do is jam in a console.log() call at the point where I wanted to know a value, and fire up Chrome’s console to see what’s what.

The issue with this method arises when you use build tools, like we do with WP Migrate DB Pro. You have to wait for the build task to complete to see your output – losing valuable seconds of your day. It’s also a pretty simplistic way to view your JavaScript code and doesn’t give you the full picture.

Chrome does have a decent debugger built into the developer console. However, for me it always felt disjointed to use an external debugger not in my IDE. I’ve used the Chrome debugger in the past but I prefer the PhpStorm debugger for a few reasons.

The first advantage of the PhpStorm debugger is that it allows you to define tasks or scripts to run before debugging is started. If you have a grunt or gulp task that compiles your scripts this is a helpful addition.

Debug configuration

The second advantage is having breakpoints reliably saved between page refreshes with the PhpStorm debugger. The Chrome debugger won’t save breakpoints between page loads if there is a cache busting string appended to the URL in a script tag. Removing the random string and/or setting up source maps for your scripts would help with this, but it’s not always possible.

Finally, the biggest advantage of the PhpStorm JavaScript debugger is it’s integration with the Xdebug PHP debugger. As we’ll soon see, both JavaScript and PHP can be debugged during the same session.

The Setup

The first thing you’ll want to do is check out the Jetbrains documentation on configuring the JavaScript debugger. It goes over the main steps required to get things up and running.

The next thing you’ll want to do is make sure you’re using the Chrome web browser. Things seem to work best with Chrome, though there is a Firefox configuration as well. Then you’ll need to install the Jetbrains Chrome extension so that Chrome and PhpStorm can talk to each other.

For the purposes of this post, we’re going to go over Remote Debugging as my local dev sites all use separate local domains and to PhpStorm they are ‘remote’. It’s a little confusing, but I had the best success following the instructions for a remote server.

In order to enable remote debugging of JavaScript, you’ll need to create a permanent debug configuration. To do this, let’s click on “Run” in the top menu bar, and then click on “Edit Configurations”. We’ll start by clicking on the “+” button and selecting “JavaScript Debug”.

In this screen we’ll enter our name for this debug configuration and select a starting URL. I’m using the WP Migrate DB Pro admin page, but you could just as easily use a front-end URL for your own setup.

Furthermore, if the URL matches the PHPStorm project you’ve currently got open, that should be all you need to get up and running! Otherwise, you can map a domain or URL to your current project by using the “Remote URL” section of the debug configuration.

Debug configuration

Debuggin’

If all went well we should now be all set up to debug us some JavaScript. To do that we’ll need to use some breakpoints. A really important thing to note here is that your breakpoints have to be placed in the JavaScript files that the browser loads. If you’re not using a build tool in your workflow, you’re all set.

However, if you do use a build tool (like Grunt, Gulp or Webpack) you’ll have to make sure your breakpoints are in the files that are output by the build process. So, if you have a /dist folder where your assets are stored, make sure the breakpoints are in these files, rather than in the source JS files.

Script files to place breakpoints in

It’s important to note that you’ll want to avoid minifying your built files locally during development and save minification for a final ‘build’ step.

Alternatively, if you have source maps enabled in your build process you may be able to add your breakpoints directly to your source JavaScript files. There is an issue with WebStorm/PhpStorm and Browserify’s inline source maps, but there is a workaround.

In our case, with WordPress’ SCRIPT_DEBUG enabled, we’re able to load the unminified built files. That may be an option for you as well.

I should also mention that PhpStorm essentially takes over Chrome’s developer console when you’re debugging. This means that the debugger won’t work if the Chrome console is open on the tab you’re running the code. A small issue, but it’s caught me a few times.

Breakpoints

Now that we know where to put our breakpoints, let’s add some. In PhpStorm it’s as simple as clicking in the margin on a line we want to break on. There are a few other options for breakpoints, but for our purposes we’re going to use a regular line breakpoint.

Once we’ve set up our breakpoints, we’ll click on the “bug” icon in the top menu bar, or under the “Run” menu > Debug. This should open up Chrome with a yellow bar across the top saying “JetBrains IDE Support is debugging this browser”. Once you do something in the browser that triggers the code flagged with a breakpoint, you’ll be booted back to PhpStorm with the debugger open.

In the debugging console, you’ll have all your favourite debugging tools you get with Xdebug PHP debugging, but also a new tool for debugging asynchronous code. This can be toggled with the ‘Async’ checkbox in debug panel. This little guy will let you step into asynchronous code. Clicking on this checkbox will give you access to the whole call stack from within the async callback, whether it’s AJAX or something like a setTimeout() call.

For me this came in handy when I was debugging the JavaScript for WP Migrate DB Pro’s Media Files Addon. I was looking into how the large files are handled during a ‘push’ migration and narrowed down the logic to a few lines of JavaScript. With my new found JS debugging tools I set up some break points and went to work.

From there I was able to see how and when each segment of the if statement was triggered.

Other Tools

Another handy tool is PhpStorm’s built in “watches” functionality. It allows you to set items in your code to be watched – meaning the debugger will display this item’s value in the watches pane. This is helpful for things you would normally output with a console.log call as that’s essentially what it does, outputs the watched variable’s value as breakpoints are triggered. It’s helpful because it saves you time tracking down the variable in the debug panel each time you restart the debugger.

Watch pane in debugger

In the case of the above example, I was watching the wpmdb global variable so that I had quick access to it when the breakpoints fired.

Another trick with the PhpStorm debugger that I use quite often is the “Evaluate Expression” tool. With this tool you can inspect and calculate values based on the currently paused code.

Evaluate expression example

In the example above I saw that the AJAX call returned a data variable in a jQuery AJAX success callback. However, the data returned was a JSON string and I wanted it to be nicely formatted. With the “Evaluate Expression” tool I could use the jQuery $.parseJSON() method to output a formatted JavaScript object for further inspection. This tool is also available when you’re using the PHP Xdebug debugger.

Integration with Xdebug

Lastly, I want to cover one more feature that I think is the most awesome aspect of the PhpStorm debugger – the ability to debug your JavaScript code and PHP code during the same debugging session. You can watch a value as it’s transferred from the front-end JavaScript to the back-end PHP. This is especially helpful for dealing with AJAX calls and their back-end handlers.

For example, say you’re posting some values via AJAX to your PHP backend and they’re coming through corrupted. You can set some breakpoints in your JavaScript to inspect the values before they’re sent to the server and then inspect them as soon as the server receives them.

While you could certainly use the Chrome debugger to inspect the JavaScript values, you’d have to switch back to PhpStorm to inspect the values as they’re interpreted. The seamlessness provided by the integrated PhpStorm debugger is extremely helpful as you don’t need to leave your IDE while debugging.

To debug both your JS and PHP, you have to have Xdebug already enabled and setup with PHP and PhpStorm. I won’t go over that here, but here is a good post to get you up and running with MAMP.

Assuming you have PHP configured to run Xdebug, you’ll need to click on the “phone” icon to start listening for PHP Xdebug connections. After that, start JavaScript debugging by clicking on the “bug” icon. In this scenario we’re using PhpStorm’s “Zero Configuration Web Debugging” with the saved Javascript debugging profile we created earlier.

Debugging icons

Once you have PhpStorm listening for Xdebug connections as well as JavaScript debugging started you’re all set. If you have breakpoints in your PHP code those will get triggered as they’re hit in the program execution. You can toggle between JavaScript debugging and PHP debugging by clicking on the two tabs above the debugging panel.

Scratching the Surface

And that summarizes some of the JavaScript debugging functionality in PhpStorm. Coupled with Xdebug for PHP, it’s a powerful combination to aid in debugging and digging into complex code. This is only a portion of what the PhpStorm debugger can do, but I hope it encourages you to give it try!

Do you use the PhpStorm debugger? What are some ways you use to debug complex JavaScript code? Let us know in the comments!

About the Author

Peter Tasker

Peter is a PHP and JavaScript developer from Ottawa, Ontario, Canada. In a previous life he worked for marketing and public relations agencies. Loves WordPress, dislikes FTP.

  • Danny Froberg

    Good write up 🙂

  • Good stuff, thank you! I live and die by the PHP debugger, it’s been an invaluable tool for productivity and learning. I haven’t dug in to the JS debugger yet but have been wanting to. This will be super helpful, and thanks for posting the resources for working with minified assets and source maps.