If you keep up with the many text editors and developer tools available, you may have heard of Microsoft’s Visual Studio Code. VS Code is a free, open source code editor that is lightweight like Sublime Text, but offers many of the same features as bigger IDEs like PhpStorm or WebStorm.

In this article I’ll review some features of VS Code that I love, and show you how to make the most out of it for WordPress dev.

Basic Setup for WordPress Development

Most of the time when coding in WordPress, you’ll either be working on a plugin or a theme. One way to do this might be to open that plugin or theme in your IDE and start coding away. There is a better way though, with the help of VS Code “Workspaces”.

You can think of a Workspace in VS Code as a container for your project – it not only includes your project, but it can include files that your project relies on (your WordPress installation), and any extensions or settings specific to that project.

I like Workspaces because you can create one of them for each project and change any setting or extension in VS Code at the Workspace level. For example, you may not want to use the WordPress Coding Standards on all of your projects, or maybe you work with a team of developers that can’t agree on tabs vs. spaces.

In my case, the vast majority of my time is spent on plugin development. So I’ll have a Projects folder that has all of the plugins I work on, and a Sites folder that contains all of my sites. I’ll then symlink the plugin I’m working on into a fresh WordPress website in the Sites folder.

In Visual Studio Code, I’ll first open the plugin itself, and then I’ll add the WordPress site by selecting File -> Add Folder to Workspace. That sets up a new Workspace where I can edit the plugin and the WordPress installation at the same time.

This is handy for quick edits to the wp-config.php file, and keeping an eye on the debug.log file while I’m developing.

Next, click File -> Save Workspace As to save that Workspace. This creates a *.code-workspace file that you can use to open your Workspace again in the future, and also serves as a config file that will come in handy later.

Deeper PHP and WordPress Integration

With that out of the way, let’s take a look at how we can make Visual Studio Code and WordPress play a bit nicer. Out-of-the-box, VS Code doesn’t support WordPress and PHP as well as some other IDEs like PhpStorm (Find out how some of our team uses PhpStorm for WordPress Development). Luckily, that’s easy to change by installing some extensions.

Since WordPress is still mostly PHP, I use the PHP Intelephense extension, which adds PHP auto-completions, symbol navigation support, and a much better way to find references in your workspace.

While that will add auto-completions for PHP core functions and anything that you have defined in your project, it won’t pick up on much from WordPress core. For that there is the WordPress Snippet extension, which will autocomplete WordPress core functions, classes, and constants. It even will add WordPress function argument type hints, which often helps save a trip to the docs.

These tools make it much easier to work with WordPress plugins and themes, and PHP development in general.

Debugging PHP

xDebug is an invaluable tool to have for debugging PHP, but it can be tricky to set up. Luckily, VS Code makes it easy to configure xDebug, and in my case it just works.

You only need to install the PHP Debug extension and reload the editor. You can then go to the “Run” tab and click “create a launch.json file” to create a new PHP debug configuration.

You should then see a pop-up towards the top of your editor asking you to select a Workspace folder to create the configuration in:

Select “workspace” to insert the new configuration into your *.code-workspace file, and then “PHP” to add a PHP configuration. This will add some debug config to that file, including the new “Listen for XDebug” option. You can edit the name of the configuration or change the XDebug port here.

{
    "name": "Listen for XDebug",
    "type": "php",
    "request": "launch",
    "port": 9000
},

In my case, it also added a “Launch currently open script” config as well. With WordPress, we rarely need to load a PHP file directly, so I just deleted that config.

That’s it! You should be able to start debugging PHP from here. Head over to a PHP file in your WordPress plugin or theme, and click to the left to a line number to add a breakpoint to that line.

When you head back over to the “Run” tab, select “Listen for XDebug” from the dropdown and click the play icon to start listening for requests. When your code hits that breakpoint, the runtime should pause and you can see all variables, the call stack, and more. Who knew debugging WordPress in Visual Studio Code could be so easy?

Debugging JavaScript

Debugging PHP is only half the problem – we also need to be able to debug JavaScript. Since I use Mozilla Firefox as my main browser, I installed the Debugger for Firefox extension which integrates VS Code with Firefox.

Next, you’ll need to edit the *.code-workspace add some config for JS:

{
    "name": "Listen for JS",
    "type": "firefox",
    "request": "launch",
    "url": "http://yoursite.dev",
    "webRoot": "/path/to/your/site/root",
}

Once that’s been added, you should see the Listen for JS option in the debug drop down:

For reference, here’s my entire mdb.code-workspace file so far:

{
"folders": [
    {
    "path": "wp-migrate-db-pro"
    },
    {
    "path": "/Users/mattshaw/Sites/mdb/app/public"
    }
],
"launch": {
    "version": "0.2.0",
    "configurations": [
    {
        "type": "firefox",
        "request": "launch",
        "name": "Listen for JS",
        "url": "http://mdb.test",
        "webRoot": "/Users/mattshaw/Sites/mdb/app/public"
    },
    {
        "name": "Listen for XDebug",
        "type": "php",
        "request": "launch",
        "port": 9000
    }
    ]
}
}

Gotchas

If you’re using something like Webpack to bundle your JS files together, you may notice that your breakpoints aren’t working. You can use the sourceMapPathOverrides param in your *.code-workspace file to manually map the file paths correctly, but Debugger for Firefox has an easier solution.

If the debugger detects that the file you created a breakpoint in wasn’t loaded during a Firefox request, you should see the following prompt:

Simply click “Yes” to let the Path Mapping Wizard figure out the correct path for you. I’ve never been more grateful to such an obscure wizard in my life.

With that in place, it’s now easy to debug JS from within VS Code, using the same UI that is used for xDebug:

Other Tips

I’ve come across some other important extensions that have been helpful in day-to-day development. The Git Lens extension adds simple git blame annotations to the line that you’re currently working on. This single line annotation of git blame works noticeably faster than PhpStorms’ implementation, which tries to run on the whole file at once. Unfortunately, it doesn’t have a GitHub integration, but even without it I still feel that it’s handy enough to keep around.

The PHP DocBlocker extension is super helpful for, well, docblocking. Simply type /** above a function, method, or class and it will autocomplete the docblock based on the function/method parameters.

The Prettier extension is great for cleaning up your CSS, JS, and HTML code on editor save.

If you work with a lot of modern JS it’s also worth installing the Babel ES6/ES7 extension, which adds syntax highlighting for ES6/ES7. I also have the Instant Markdown plugin installed, which I used to write this post and is a cool way of previewing your markdown in the browser.

Closing Thoughts

After using it for three years, I still love VS Code. It’s like it took my favorite features of PhpStorm and Sublime Text, and combined them to create the perfect IDE (see how it beats out other PHP IDE/Editors for WordPress development in our comparison). I also really like the way that you can install extensions directly from within VS Code, and view the docs for that extension without leaving the editor.

I’ve since removed PhpStorm and Sublime Text from my dock, and don’t have plans to bring them back.

Have you tried out VS Code yet? What did you think? Let us know in the comments.