Integrating Visual Studio Code with WSL2, DDEV & Drupal

This page explains how to integrate Visual Studio Code (VS Code) with the Windows Subsystem for Linux (WSL2), DDEV & Drupal.

Visual Studio Code (VS Code) is a very popular, free, open source IDE (Integrated Development Environment) built by Microsoft. If you prefer to avoid Microsoft's license and telemetry, VSCodium is an alternative distribution based on the same vscode repository.

Another IDE that is popular amongst Drupal developers is PhpStorm. It is powerful and ships with more PHP-specific features than VS Code, but it is subscription-based. This guide will show you how to integrate VS Code with DDEV and Drupal by installing and configuring appropriate VS Code extensions. It then explains how to install and configure some useful VS Code extensions that can make your Drupal development more efficient.

We'll assume you already have VS Code installed with some basic configuration. If not, consult the VS Code documentation, or check out countless online tutorials.

We'll also assume you have installed WSL2, Ubuntu, Docker, DDEV & Drupal as explained in the previous pages of this guide.

With WSL2, Ubuntu & VS Code installed, you can open VS Code in Windows from your Ubuntu terminal by simply entering code.

WSL extension

It is entirely possible to work in a Windows folder such as \\wsl.localhost\Ubuntu\home\my-name\sites\my-drupal-project in VS Code, but you would be missing an Ubuntu terminal within VS Code, and features such as autocomplete, debugging, and linting.

Microsoft's WSL VS Code extension, formerly known as Remote - WSL, allows you to use your native Windows VS Code installation to develop your applications hosted within WSL2. It is essential for a fully-featured workflow. When VS Code detects that you have WSL on your system, the WSL extension will rise to the top of the recommended extensions and you may also be prompted to install it. 

Go ahead and install from that prompt, or from the Install link on the extension's page, or from the Extensions panel in VS Code.

With the WSL extension installed, a new Remote Explorer icon will be added to the Activity Bar on the far left, the same as if you installed the Remote Explorer extension. Click on that icon to see a list of WSL targets. Hover over the name of your Drupal project container and click the right arrow to connect in the current window. Select Yes, I trust the authors when prompted. It's not a bad idea to also check the box to trust the authors of all files in the parent folder.

The folder title at the top of the VS Code window and above VS Code's Explorer panel will now be followed by [WSL: UBUNTU], and VS Code's terminal will now be an Ubuntu terminal where you can run commands just as you would in a separate Ubuntu terminal.

Note that if you attempt to open a folder below \\wsl.localhost in the Windows file system, you would be prompted to reopen it in WSL.

If you open further Drupal projects from your Ubuntu terminal by entering code, click Open Folder in the Explorer panel and then choose your Drupal project folder.

VS Code settings hierarchy

With WSL2/Ubuntu and the WSL extension installed, VS Code settings can be applied at 3 cascading levels.

• User - This is the top level. Settings here apply to any of the user's VS Code windows and workspaces, whether they are WSL windows or not. User settings are stored in your Windows file system at %AppData%/Code/User/settings.json.
• Remote [WSL: Ubuntu] - These settings apply to all WSL windows and workspaces. They will override User settings. These settings are stored at ~/.vscode-server/data/Machine/settings.json.
• Workspace - These settings apply only to the individual workspace. They will override User and Remote [WSL: Ubuntu] settings. Workspace settings are stored at ~/path-to-project/.vscode/settings.json.

On each Settings page in the VS Code GUI, an icon linking to the corresponding settings.json file is shown at the top right. It's often easier to change VS Code settings by editing that file directly.

Cannot validate... warning

If you don't have PHP installed globally, when you open a PHP script in VS Code you will probably get a warning from VS Code's in-built PHP Language Features extension: Cannot validate since a PHP installation could not be found...

If you wish to use the PHP Sniffer & Beautifier and/or the phpstan extensions described later, unfortunately you will need to install PHP globally, because those extensions can't "see" the containerized, local PHP provided by Docker. However, if you don't wish to use those 2 extensions, then we can trick PHP Language Features into seeing Docker's PHP.

Change to your home directory by entering ~, then create a new file that will act as a "dummy" script called php containing this code:

path=$(printf '%s\n' "${PWD##*/}")
command="ddev php "$@""
$command

If you still have wslu installed, you can create and edit the php file by entering touch php then wslview php. Open the php file in VS Code when prompted, then close VS Code after saving the file.

Alternatively, create and edit the php file with a text editor such as nano: nano php

Move the file to a global directory in our path:

sudo mv php /usr/local/bin

Make the file executable:

sudo chmod +x /usr/local/bin/php

Validate that php can be found without preceding it with ddev :

php -v

Re-open your project in a VS Code WSL window. The warning should not appear.

Other VS Code extensions

If you already had VS Code installed with extensions, the LOCAL - INSTALLED section of VS Code's Extensions panel will show that UI Extensions are enabled, while Workspace Extensions (those that can access files) are disabled with a blue Install in WSL: Ubuntu button (more info). Install any existing extensions you wish to use within WSL2, but consider holding back on any that may duplicate the function of the extensions listed below.

As you install Workspace Extensions, they will be listed in the WSL: UBUNTU - INSTALLED section in VS Code's Extensions panel.

Below is guidance on installing and configuring some useful VS Code extensions, specifically in a DDEV/WSL2 environment. For other useful extensions, see Configuring Visual Studio Code - Recommended Extensions.

DDEV Manager extension

Biati Digital's DDEV Manager Vs Code extension provides management of your DDEV projects from within VS Code. After installation you will see a new DDEV logo in the VS Code Activity Bar. Click on it to see a panel listing your DDEV projects. Projects that are started have a green circle. Click the angle bracket at the left to see information about the project. To the right of running projects there are buttons to open the project in your browser, start an SSH session, restart the project, and stop the project. Under the ... you can find various other commonly-used DDEV commands.

In the extension's settings, after choosing your Docker Provider and your Default Database Manager (in this example, Adminer), you will have 2 lines similar to these in your user settings.json file:

"ddevManager.dockerProvider": "Docker CE",
"ddevManager.defaultDatabaseManager": "Adminer",

Drupal Smart Snippets

Andy Blum's Drupal Smart Snippets VS Code extension adds rich language support for the Drupal Hooks API and Drupal Form and render elements. It saves you time by intelligently suggesting replacements for hooks and elements. This extension has no settings.

PHP Debug

Xdebug's PHP Debug VS Code extension is an adapter that enables you to do step debugging in VS Code. This, for example, enables you to step through a script to see the value and type of variables without echoing or printing them to your browser.

For guidance on setting it up, see Step Debugging with Xdebug in the DDEV Docs. The following settings in the launch.json file in your project's .vscode folder work well. See here for a description of each setting.

{
 "version": "0.2.0",
 "configurations": [
   {
     "name": "Listen for Xdebug",
     "type": "php",
     "request": "launch",
     "port": 9003,
     "pathMappings": {
       "/var/www/html": "${workspaceFolder}"
     },
     "log": false,
     "xdebugSettings": {
       "show_hidden": 1,
       "max_children": 512,
       "max_data": 1024,
       "max_depth": 4,
     }
   }
}

When used with DDEV, PHP Debug does not require any custom settings. It works without setting a value for the executable path ("php.debug.executablePath").

There are many online tutorials for using Xdebug with VS Code, along with the Xdebug documentation. Here is one very simplified step-debugging example procedure:

1. Start the service by running ddev xdebug in your Ubuntu terminal.
2. Set breakpoints (red dots next to the line numbers) in your script.
3. Click the Run and Debug logo in the VS Code Activity Bar.
4. Click the green Start Debugging button next to Listen for Xdebug.
5. Open or refresh the page in your web browser.
6. When the script pauses on your first breakpoint, inspect the variable values in the VARIABLES panel.
7. Click the Continue button (center top) of press F5 to go to the next breakpoint.
8. When you are finished, run ddev xdebug off to save on system resources.

Note: Ensure that in VS Code the project is opened in the same folder where you run the ddev xdebug command. Otherwise the breakpoints do not work.

PHP Intelephense

Ben Mewburn's PHP Intelephense VS Code extension is a PHP language server with several features such as code completion, signature help and diagnostics. As you hover over variables and function names etc., information about them will pop up like a tooltip.

It's a good idea to set Intelephense settings as workspace settings so they can be different per project. For a Drupal project with a document root relocated to a web folder (as per the Drupal recommended project), under PHP 8.3, with Drupal-compatible braces, these 3 entries would be in your workspace settings.json:

"intelephense.environment.phpVersion": "8.3",
"intelephense.environment.documentRoot": "web/",
"intelephense.format.braces": "k&r",

Global PHP for PHP Sniffer & Beautifier & phpstan

Unfortunately, at least with DDEV installed in WSL2, the PHP Sniffer & Beautifier and phpstan VS Code extensions described below cannot use the local, containerized PHP provided by Docker. So we have to install PHP globally within Ubuntu. This is not ideal, as it defeats the purpose of containerized projects. For accurate code suggestions, you will have to keep the global version of PHP in sync with your DDEV project version. In the future, hopefully someone will find a way for these extensions to use Docker's containerized PHP.

If you did the "dummy" php trick above, and may wish to go back to using it, rename it:

sudo mv /usr/local/bin/php /usr/local/bin/phpDUMMY

or delete it if you're sure you want to use these extensions:

sudo rm /usr/local/bin/php

First update Ubuntu and its packages:

sudo apt update && apt upgrade

Add the PHP repository (press ENTER when asked):

sudo add-apt-repository ppa:ondrej/php

Install php-fpm, to stop unnecessary Apache getting later installed as dependency. Choose a PHP version to match your DDEV projects (if you use multiple PHP versions, see below). For PHP 8.3, for example, use this line (answer "y" when asked):

sudo apt install php8.3-fpm

Then install PHP itself. For PHP 8.3:

sudo apt install php8.3

Map php to our newly-installed binary:

sudo update-alternatives --set php /usr/bin/php8.3

For PHP Sniffer & Beautifier, you'll need one more PHP extension:

sudo apt install php8.3-xmlwriter

Multiple PHP versions

If you have DDEV projects using different versions of PHP, you can install multiple global versions of PHP, for example 8.3 and 7.4, and use Ubuntu's update-alternatives command as a switch, to map php to whichever one you wish to use. To list the alternatives and choose between them, run:

sudo update-alternatives --config php

Alternatively you could just install the higher version of PHP and follow the code suggestions based on that. That's good for future-proofing your code, but take care not to use a new PHP feature that is not in your server's older version.

PHP Sniffer & Beautifier

Samuel Hilson's PHP Sniffer & Beautifier VS Code extension is one of a few extensions that provide an interface to PHP_CodeSniffer, which helps you detect and fix coding standard violations.

After installing global PHP, as described above, you'll need the php_codesniffer package installed. You can get this as a requirement of Drupal Coder. Note that if you have drupal/core-dev installed, you'll have Coder anyway as a dependency. From in your project folder:

ddev composer require --dev drupal/coder

Alternatively, if you only want php_codesniffer:

ddev composer require --dev squizlabs/php_codesniffer

Make sure phpcs and phpcbf are executable:

chmod +x vendor/bin/phpcbf
chmod +x vendor/bin/phpcs

For suggestions as you type, set this in your user settings.json file:

"phpsab.snifferMode": "onType",

Put these 2 entries in your Remote [SWL: Ubuntu] settings.json file:

"phpsab.executablePathCBF": "vendor/bin/phpcbf",
"phpsab.executablePathCS": "vendor/bin/phpcs",

For Drupal projects, there are 2 rulesets: Drupal is intended to enforce the general standards, while DrupalPractice is aimed at module developers who want to avoid common mistakes. To enable both, put this entry in your workspace settings.json:

"phpsab.standard": "vendor/drupal/coder/coder_sniffer/Drupal,DrupalPractice",

phpstan

SanderRonde's phpstan VS Code extension integrates the PHPStan (PHP Static Analysis) library. This highlights errors in your code as you type, shows the values of variables as you hover, and adds a command for running project-wide analysis.

After installing global PHP, as described above, you'll need the phpstan package installed. You can get this as a requirement of Drupal Coder. Note that if you have drupal/core-dev installed, you'll have Coder anyway as a dependency. From in your project folder:

ddev composer require --dev drupal/coder

Alternatively, if you only want PHPStan:

ddev composer require --dev phpstan/phpstan

Make sure phpstan is executable:

chmod +x vendor/bin/phpstan

Make a file called phpstan.neon in your project folder, to hold your PHPStan settings. First, change to your project folder:

cd ~/path-to-my-project-folder

If you still have wslu installed, you can create and edit the phpstan.neon file by entering touch phpstan.neon then wslview phpstan.neon. Choose VS Code or a text editor if Windows asks how to open *.neon files.

Alternatively, create and edit the phpstan.neon file with a text editor such as nano: nano phpstan.neon

PHPStan has different rule levels, depending on how strict you want it to be. The default is level 0, but you may like to make it stricter, or increase the level as you learn. The higher levels can be difficult to satisfy. For example, level 5+ imposes type checking of arguments passed to methods and functions, so you cannot satisfy it by relying on type coercion and you may feel the code required to satisfy it is unnecessary.

For rule level 0, with PHPStan enabled for your Drupal modules and themes folders, paste this text into your phpstan.neon file:

parameters:
    level: 0
    paths:
        - web/modules
        - web/themes

To enable PHPStan in all your projects, put the following 2 entries in your user settings.json file. You can always override them in your workspace settings if you don't want PHPStan to run in a particular project.

"phpstan.enabled": true,
"phpstan.showProgress": true,

Finally, put these 2 entries in your Remote [SWL: Ubuntu] settings.json file:

"phpstan.binPath": "vendor/bin/phpstan",
"phpstan.configFile": "phpstan.neon",

Next steps

Having integrated Visual Studio Code with your WSL2/DDEV/Drupal environment, you are now ready to configure couple of best-practice settings before you continue with development.