WSL (Windows Subsystem for Linux)

This page documents the WSL-specific code path in this package: how WSL is detected, how mcp.json is written to the Windows filesystem from within a WSL shell, and how MCP commands are transformed so PhpStorm (running on native Windows) can invoke them. For the general platform detection and mcp.json write paths on macOS and Linux, see 5.1. For Windows native support, see 5.2. For Sail-in-WSL specifics, see 5.4.

---

Supported Topology

The WSL path applies to one specific setup: PHP (and artisan) runs inside WSL, while PhpStorm runs on native Windows. PhpStorm reads mcp.json from the Windows filesystem and spawns subprocesses on Windows, so the generated mcp.json must live there and must use wsl.exe to cross the boundary back into the Linux environment.

Sources: README.md25-84 src/Concerns/WithWSL.php1-129

---

Prerequisites

Requirement	Check	Install
wslu package (provides wslvar)	wslvar -v	sudo apt install wslu
WSL Interoperability enabled	powershell.exe -Command "Write-Output 'test'"	See below
PowerShell accessible from WSL	Command above should succeed	Verify /init binfmt config
User profile on C drive	wslvar LOCALAPPDATA returns C:\Users\...\AppData\Local	Default for most installs

If WSL Interoperability is disabled, enable it:

Sources: README.md29-59

---

Detection: isWSL()

WSL detection in WithWSL is a single environment variable check:

src/Concerns/WithWSL.php11-14

WSL_DISTRO_NAME is automatically set by WSL in every shell session. If this variable is present and non-empty, the entire WSL pipeline activates in installFileMcp.

The check is invoked inside PhpStormCopilot::installFileMcp after the Testbench guard and before the Sail transformation:

src/PhpStormCopilot.php119-132

Sources: src/Concerns/WithWSL.php11-14 src/PhpStormCopilot.php119-132

---

Installation Pipeline: installMcpViaWsl()

When isWSL() returns true, control passes to installMcpViaWsl() in the WithWSL trait. This method bypasses the standard parent::installFileMcp() entirely because it must write a file to the Windows filesystem.

Title: installMcpViaWsl Step-by-Step Flow

Sources: src/Concerns/WithWSL.php16-76

Step Detail

Step	Mechanism	Code Location
Get Windows path	Process::run('wslvar LOCALAPPDATA')	src/Concerns/WithWSL.php19-22
Read existing config	powershell.exe ... Get-Content ... -Raw	src/Concerns/WithWSL.php30-33
Transform command	transformMcpCommandForWsl()	src/Concerns/WithWSL.php40
Clean config	removeEmptyArrays() (defined in PhpStormCopilot)	src/Concerns/WithWSL.php48
Encode content	base64_encode($jsonContent)	src/Concerns/WithWSL.php57
Write temp file	powershell.exe [System.IO.File]::WriteAllBytes(...)	src/Concerns/WithWSL.php58-61
Move to final location	powershell.exe New-Item ... Copy-Item ... Remove-Item ...	src/Concerns/WithWSL.php68-74

The final file is written to: %LOCALAPPDATA%\github-copilot\intellij\mcp.json

Base64 encoding is used to safely transfer the JSON string through PowerShell's command-line argument parsing, which would otherwise interpret special characters in the JSON.

Sources: src/Concerns/WithWSL.php16-76

---

Command Transformation: transformMcpCommandForWsl()

Because PhpStorm runs on Windows, it spawns wsl.exe directly. The mcp.json entry must use wsl.exe as the command so PhpStorm can invoke the Linux PHP process across the WSL boundary.

transformMcpCommandForWsl() handles three distinct input cases:

Title: transformMcpCommandForWsl Branch Logic

Sources: src/Concerns/WithWSL.php85-128 tests/Feature/PhpStormCopilotTest.php92-202

Case Reference Table

Case	Example command	Output command	Output args
Sail (relative)	./vendor/bin/sail	wsl.exe	['--cd', base_path(), './vendor/bin/sail', 'artisan', 'boost:mcp']
Sail (absolute)	/home/user/project/vendor/bin/sail	wsl.exe	['--cd', base_path(), './vendor/bin/sail', 'artisan', 'boost:mcp']
Sail (Windows-style path)	C:\Users\...\vendor\bin\sail	wsl.exe	['--cd', base_path(), './vendor/bin/sail', 'artisan', 'boost:mcp']
Already wsl.exe	wsl.exe	wsl.exe	unchanged
Direct PHP path	/usr/bin/php	wsl.exe	['--cd', base_path(), '/usr/bin/php', ...args]

The --cd flag tells wsl.exe to change into the specified directory before executing, which is important for commands that rely on the working directory.

Note that both str_ends_with($command, '/vendor/bin/sail') and str_ends_with($command, '\\vendor\\bin\\sail') are checked so that Windows-style paths from Sail in WSL contexts are correctly recognized — see src/Concerns/WithWSL.php88

Sources: src/Concerns/WithWSL.php85-128 tests/Feature/PhpStormCopilotTest.php92-202

---

Class and Trait Relationships

Title: WithWSL Trait — Class Integration

The WithWSL trait calls $this->removeEmptyArrays() and $this->mcpConfigKey(), both of which are defined in PhpStormCopilot. This means WithWSL is only correct when used within PhpStormCopilot or a class providing those methods.

Sources: src/PhpStormCopilot.php15-17 src/Concerns/WithWSL.php1-129

---

Known Limitations

Remote Development (PhpStorm inside WSL)

Running PhpStorm via Remote Development within WSL is not supported by the automated pipeline. The package cannot distinguish between:

• PhpStorm on Windows + PHP in WSL (the supported topology)
• PhpStorm remote-developing inside WSL (unsupported)

Both environments present as Linux from the PHP process's perspective. In the remote development case, WSL_DISTRO_NAME will not be set (since PHP is also inside WSL and PhpStorm bridges into it), so isWSL() returns false and the standard Linux path is taken — which writes to ~/.config/github-copilot/intellij/mcp.json inside WSL rather than on the Windows host.

For Remote Development, configure mcp.json manually:

Sources: README.md62-81

Testbench

The Testbench guard in installFileMcp fires before the WSL check. If TESTBENCH_CORE is defined, an Exception is thrown. See src/PhpStormCopilot.php121-123

Alternative Tool

For project-level (non-system-wide) MCP configuration in WSL, the README recommends laravel-boost-copilot-cli as an alternative that avoids the system-wide mcp.json constraint. See README.md84

Sources: README.md62-88 src/PhpStormCopilot.php119-127