This guide aims to be the reference for setting up Lando and PhpStorm tools on a WSL2 environment.

This assumes your project:

• lives in a WSL2 instance (something like \\wsl$\Ubuntu\home\[user]\dev\my-demo-project)
• Is "Lando-initialized" (lando init) and runs (lando start)
• uses Composer, and dependencies are installed (lando composer install)

This guides relies on Docker for Windows, using the WSL2 based engine, and setup with WSL integration (Resources > WSL Integration). Unfortunately I didn't find a solution to do without it and only rely on WSL's Docker.

In PhpStorm:

1. Go to File | Settings | Build, Execution, Deployment | Docker
2. Add a "Docker for Windows" item and make sure connection is successful.

To be able to run all tools, PhpStorm needs to know how to execute PHP.

Go to File | Settings | PHP

1. Click on the ... button to the right of the CLI Interpreter dropdown
   1. Click on the top-left + button and select "From Docker, Vagrant, VM, WSL, Remote..."
      1. Choose "Docker Compose"
      2. Select your "Docker for Windows" server
      3. On the "Configuration files" line, click on the folder icon
         1. Remove all the pre-existing lines
         2. Click on the top-left + button
         3. Navigate to your WSL's .lando folder and locate your project's compose's YAML files (something like \\wsl$\Ubuntu\home\[user]\.lando\compose\mydemoproject)
         4. Select all YAML files
         5. Click "OK"
      4. Click "OK"
   2. In the Service dropdown, select appserver
   3. Click "OK"
2. You should see Lando's PHP version
3. In the "Lifecycle" section, choose "Connect to an existing container"
4. Click "OK"

On the "Path mappings" line, click on the folder icon, then:

1. Click on the top-left + button
2. In the "Local Path" field select your project directory (something like \\wsl$\Ubuntu\home\[user]\dev\my-demo-project)
3. In the "Remote Path" field enter /app

Go to File | Settings | PHP | Composer

1. In the "Execution" section, choose "Remote interpreter"
2. Choose your "appserver" CLI Interpreter
3. Click "OK"

You can now open composer.json, see installed versions, and update them using the gutter icons.

Make sure PHP CS Fixer is installed (lando composer require --dev friendsofphp/php-cs-fixer).

In composer.json you should see a cog icon next to your friendsofphp/php-cs-fixer line. Click on it to configure it.

1. Click on the top-left + button
   1. Choose your "appserver" CLI Interpreter
   2. Click "OK"
2. In the "PHP CS Fixer Path" field, enter vendor/bin/php-cs-fixer¹ (make sure it has execute permission)
3. Click "Validate", you should see PHP CS Fixer's version
4. Click "OK"

Go to File | Settings | PHP | Quality Tools and expand the "PHP CS Fixer" section.

1. Select your "appserver" configuration
2. Select the "Custom" Ruleset and enter .php-cs-fixer.dist.php (or similar) in the path field¹
3. Turn on the inspection using the switch on the left
4. Optionally choose "PHP CS Fixer" as the External Formatter, at the bottom of the settings page
5. Click "OK"

Go to File | Settings | Editor | Inspections and make sure PHP CS Fixer validation is enabled.

Make sure Psalm is installed (lando composer require --dev vimeo/psalm).

In composer.json you should see a cog icon next to your vimeo/psalm line. Click on it to configure it.

1. Click on the top-left + button
   1. Choose your "appserver" CLI Interpreter
   2. Click "OK"
2. In the "Psalm Path" field, enter vendor/bin/psalm¹ (make sure it has execute permission)
3. Click "Validate", you should see Psalm's version
4. Click "OK"

Go to File | Settings | PHP | Quality Tools and expand the "Psalm" section.

1. Select your "appserver" configuration
2. Enter psalm.xml (or similar) in the "Configuration file" field¹
3. Turn on the inspection using the switch on the left
4. Click "OK"

Go to File | Settings | Editor | Inspections and make sure Psalm validation is enabled.

You can now open PHP files and see Psalm errors.

I haven't configured and used these tools myself, but I'm pretty confident the above PHP CS Fixer and Psalm steps should be enough.

Make sure your Lando project has Xdebug:

# .lando.yml
config:
  xdebug: true

Add a .lando.local.yml file next to your .lando.yml:

# .lando.local.yml
services:
  appserver:
    overrides:
      environment:
        XDEBUG_CONFIG: "discover_client_host=0 client_host=host.docker.internal"

Optionnaly add it to .gitignore.

Run lando rebuild.

When looking at your PHP interpreter configuration, you should see Xdebug's version.

Go to File | Settings | PHP | Servers.

1. Click on the top-left + button
2. Give it any name
3. Enter your Lando host (something like my-demo-project.lndo.site)
4. Choose Xdebug in the Debugger dropdown
5. Check "Use path mappings"
6. Enter /app on the right of the first/only "Project files" line
7. Click "OK"

Adding breakpoints and running your site should now break as expected.

If you get "Debug session was finished without being paused" warnings for no apparent reason:

1. Go to File | Settings | PHP | Debug
2. Expand the "Settings" section
3. Uncheck "Notify if debug session was finished without being paused"

Make sure PHPUnit is installed (lando composer require --dev phpunit/phpunit).

In composer.json you should see a cog icon next to your phpunit/phpunit line. Click on it to configure it (or go to File | Settings | PHP | Test Frameworks).

1. Click on the top-left + button
2. Choose "PHPUnit by Remote Interpreter"
   1. Choose your "appserver" interpreter
   2. Click "OK"
3. Enter vendor/autoload.php¹ in the "Path to script" field
4. Check "Default configuration file" and enter phpunit.xml.dist in the associated field¹
5. Click "OK"

You can now use your test files' gutter icons to run classes' or methods' test.

These (older) guides might help, too:

• Windows WSL2: Install Lando 3.11.0
• Windows 10/11 + WSL2 + Docker + Lando + PHP XDebug (PHPStorm, IntelliJ & Visual Studio Code (vscode))
• Xdebug config for Lando running in WSL2 and PhpStorm running in Windows
• Windows: Lando with Hyperdrive
• Lando + PHPStorm/IntelliJ IDEA + PHPUnit