Skip to content

Instantly share code, notes, and snippets.

@quentint

quentint/wsl2-lando-phpstorm.md

Last active May 1, 2024 17:38
Show Gist options
  • Save quentint/265404e9fd9a6ada2893639006c0865b to your computer and use it in GitHub Desktop.
Save quentint/265404e9fd9a6ada2893639006c0865b to your computer and use it in GitHub Desktop.
Download ZIP
WSL2 / Lando / PhpStorm
Raw
wsl2-lando-phpstorm.md

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)

Docker

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.

CLI Interpreter

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

Composer

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.

Quality tools

PHP CS Fixer

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-fixer1 (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 field1
  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.

Psalm

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/psalm1 (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" field1
  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.

Other quality tools (PHP_CodeSniffer, Mess Detector, PHPStan)

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.

Xdebug

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"

PHPUnit

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.php1 in the "Path to script" field
  4. Check "Default configuration file" and enter phpunit.xml.dist in the associated field1
  5. Click "OK"

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

Sidenotes

These (older) guides might help, too:

Footnotes

  1. The path has to be relative, do not use PhpStorm's folder button ↩ ↩2 ↩3 ↩4 ↩5 ↩6

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment