Table of Contents

Editor Integration

Summary

Connect your editor of choice (VS Code or PhpStorm) directly to your AlmaLinux 10 environment, and set up Xdebug for step debugging.

This assumes you've already completed Setup Packages and have at least one project running under a virtualhost.

VS Code (Remote - WSL)

Install the Remote - WSL extension in VS Code on Windows.

Then, from inside AlmaLinux 10, move to your project's directory and run:

code .

This opens VS Code connected to your AlmaLinux 10 distro - notice the green remote indicator in the bottom-left corner. Every extension, terminal, and file operation now runs using the Linux binaries inside AlmaLinux 10, not the Windows ones, which matters for anything that shells out to php, composer, or node.

The first time you run code . from a new distro, VS Code Server is downloaded and installed automatically inside AlmaLinux 10 - this can take a minute or two.

PhpStorm (WSL interpreter)

You install PhpStorm normally on Windows, but configure it to use the PHP interpreter inside AlmaLinux 10 instead of installing PHP on Windows.

  1. Open your project in PhpStorm.
  2. Go to Settings -> PHP.
  3. Next to CLI Interpreter, click ... and add a new interpreter.
  4. Choose From WSL, select the AlmaLinux-10 distro, and point it at /usr/bin/php.
  5. Confirm and apply.

PhpStorm can now index, run, and debug using the same PHP install the playbook provisioned, instead of a separate Windows copy.

Your project files are located inside the WSL filesystem (the default and recommended location - see WSL Configuration). You open the project from its \\wsl.localhost\AlmaLinux-10\... path in PhpStorm so file watching and indexing stay fast.

Xdebug

Xdebug isn't installed by the playbook. To add it:

sudo dnf install php-pecl-xdebug -y

Then configure it (as root) by editing the Xdebug ini file:

sudo nano /etc/php.d/15-xdebug.ini

Add or adjust:

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

Restart PHP-FPM for the change to take effect:

sudo systemctl restart php-fpm

VS Code

Install the PHP Debug extension, then add a Listen for Xdebug launch configuration on port 9003. Start listening, then request your project's URL in the browser - the debugger should stop at your breakpoints.

PhpStorm

Go to Settings -> PHP -> Debug, confirm the Xdebug port is 9003, then click the "Start listening for PHP Debug connections" icon in the toolbar and request your project's URL in the browser.

PHPUnit

Both editors can run PHPUnit using the same WSL-side PHP and Composer install:

  • VS Code: install a PHPUnit test-runner extension once connected via Remote - WSL, and point it at your project's vendor/bin/phpunit.
  • PhpStorm: go to Settings -> PHP -> Test Frameworks, add a PHPUnit configuration using the WSL interpreter configured above and your project's vendor/bin/phpunit.

Next step

See WSL Configuration for where to put your project files and how to tune WSL's resource usage, or jump to the FAQ for common troubleshooting.

On this page