Visual Studio 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’re 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 (JSON-based) that stores path folders and settings. This allows you to open your Workspace again in the future, and also serves as a config file that will come in handy later. If you’re collaborating, you can version-control this file—just ensure paths like /Sites/my-site aren’t machine-specific.

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 Hooks IntelliSense for WordPress extension. It autocompletes WordPress hooks (actions/filters) and their priority parameters. There’s also PHP Tools for Visual Studio Code, which provides advanced IntelliSense for WordPress core functions, classes, and constants. It even resolves argument orders for functions like get_posts(), so you spend less time checking the Codex.

To enforce WordPress best practices, use the WordPress Coding Standards with the PHP Sniffer extension. This combination highlights issues like missing sanitization or incorrect file naming in real time. Just install phpcs globally and configure the extension to use the WordPress standard in your workspace settings.

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. Here’s how to adjust the config based on a common MAMP setup:

{
    "name": "Listen for XDebug",
    "type": "php",
    "request": "launch",
    "port": 9003, // Xdebug v3+ uses 9003!
    "pathMappings": {
        // Docker example:
        "/var/www/html": "${workspaceFolder}/wp",
        // Local example (MAMP/XAMPP):
        "/Applications/MAMP/htdocs/mysite": "${workspaceFolder}"
    },
    "log": true // Enable logging for troubleshooting
}

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. For breakpoints to work, append ?XDEBUG_SESSION=VSCODE to your site’s URL, or add a browser extension. 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?

XDebug Ghosting You? Enable Logs

When your breakpoints mysteriously don’t trigger—even though everything seems right—you can add these lines to your php.ini to enable logs:

[xdebug]  
xdebug.log = /tmp/xdebug.log  # Simple path that’s always writable  
xdebug.log_level = 1  # 1=errors, 3=trace (verbose)  

When to Check the Logs:

• Breakpoints ignored (even with ?XDEBUG_SESSION=VSCODE).
• VS Code’s debugger says “Connected” but never pauses.
• You’re muttering “Why isn’t this working?!” at your screen.

What to Look For:

• “Could not connect to client”: Firewall blocking port 9003? Try changing the port that xDebug listens on or check your local firewall settings..
• “File is not mapped”: Fix pathMappings in launch.json (e.g., /var/www/html → ${workspaceFolder}).
• “Invalid session”: Do you have the Xdebug browser extension enabled or are you forgetting to add ?XDEBUG_SESSION=VSCODE to your URL?

Debugging JavaScript

Debugging PHP is only half the problem – we also need to be able todebug JavaScript. Thankfully, modern VS Code has robust tools for this built right in. VS Code’s JavaScript Debugger is bundled with VS Code by default and supports Chrome, Edge, Node.js, and more. No extensions needed!

Next, you’ll need to edit the *.code-workspace file to add a JS debug config. :

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

The type here refers to VS Code’s built-in JavaScript Debugger, which supports Chromium-based browsers. If you prefer Firefox, you can use Mozilla’s Firefox Debugger extension and update the type to "firefox".

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": "chrome",
        "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": 9003
        "pathMappings": {
          "/var/www/html": "${workspaceFolder}/wp"  
        }       
      }
    ]
  }
}

The pathMappings are essential if you’re using Docker or developing remotely. If you’re working locally, you only need them if your server’s file paths differ from your local workspace.

Gotchas

If you’re using something like Webpack to bundle your JS files together, you may notice that your breakpoints aren’t working. Modern tools generate source maps automatically, but if yours aren’t lining up, you should double-check your webpack.config.js for devtool: 'source-map'. Also, in VS Code’s debug config, ensure webRoot matches your server’s document root.

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 GitLens extension adds simple git blame annotations to the line that you’re currently working on. And now it even integrates with GitHub for pull request insights!

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.

VS Code’s built-in Markdown preview (no extension needed!) works great for writing docs or blog posts. And if you’re using modern JavaScript, the native syntax highlighting covers ES6+—no plugin required.

Closing Thoughts

After using it for 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. 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.

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