WithWSL Trait API

This page is the complete API reference for the WithWSL trait located at src/Concerns/WithWSL.php It covers the three methods exposed by the trait, their exact signatures, parameter contracts, return values, and the step-by-step behavior of each. For an explanation of why the WSL pipeline exists and how it fits into the broader installation flow, see 5.3. For how PhpStormCopilot calls these methods as part of installFileMcp, see 4.3.

---

Trait Location and Usage

Item	Value
File	src/Concerns/WithWSL.php
Namespace	Revolution\Laravel\Boost\Concerns
Used by	Revolution\Laravel\Boost\PhpStormCopilot
Visibility of all three methods	protected (except transformMcpCommandForWsl, which is public)

PhpStormCopilot mixes in the trait with use WithWSL; at src/PhpStormCopilot.php17

Diagram: Trait Composition

Sources: src/Concerns/WithWSL.php1-129 src/PhpStormCopilot.php17

---

Method Reference

isWSL()

src/Concerns/WithWSL.php11-14

protected function isWSL(): bool

Purpose: Determine whether the current PHP process is running inside Windows Subsystem for Linux.

Mechanism: Reads the WSL_DISTRO_NAME environment variable. The variable is automatically set by the WSL kernel for every process running in a WSL distribution. Returns true if the variable is non-empty.

Detail	Value
Visibility	protected
Return type	bool
Environment variable checked	WSL_DISTRO_NAME
Returns true when	WSL_DISTRO_NAME is set and non-empty
Returns false when	Running on native Linux, macOS, or Windows

Called from: PhpStormCopilot::installFileMcp() at src/PhpStormCopilot.php125-127 to select the WSL-specific installation branch.

Sources: src/Concerns/WithWSL.php11-14 src/PhpStormCopilot.php125-127

---

installMcpViaWsl()

src/Concerns/WithWSL.php16-76

protected function installMcpViaWsl(string $name, string $command, array $args): bool

Purpose: Write the MCP server entry into the Windows-side mcp.json from within a WSL process. Because PhpStorm runs on Windows, the config file must reside on the Windows filesystem at %LOCALAPPDATA%\github-copilot\intellij\mcp.json, which is not directly writable from Linux paths. All file I/O is performed via powershell.exe calls.

Parameters

Parameter	Type	Description
$name	string	The key to use inside mcp.json's servers object (e.g., "laravel-boost")
$command	string	The raw command string produced by laravel/boost (may be a PHP path, Sail path, or wsl.exe)
$args	array	The argument array accompanying $command

Return Value

Returns bool. Returns true when the final powershell.exe copy operation succeeds, false if wslvar LOCALAPPDATA returns an empty string or any powershell.exe process call fails. Process failures also throw via ->throw() on the Process facade result.

Step-by-Step Execution

Diagram: installMcpViaWsl Execution Steps

Internal Details

Step	Mechanism
Read Windows LOCALAPPDATA	Process::run('wslvar LOCALAPPDATA') — requires wslu package
Windows target path	{LOCALAPPDATA}\github-copilot\intellij\mcp.json
Read existing mcp.json	powershell.exe -NoProfile -Command "if (Test-Path ...) { Get-Content ... -Raw } else { '{}' }"
Config key namespace	$this->mcpConfigKey() — returns "servers" for PhpStormCopilot
Command normalization	$this->transformMcpCommandForWsl($command, $args)
Empty array cleanup	$this->removeEmptyArrays($config) — defined on PhpStormCopilot
Safe file write	JSON encoded to Base64, decoded by [System.Convert]::FromBase64String in PowerShell, written to a temp file, then copied to the final destination
Temp file name	mcp_{uniqid()}.json written into {LOCALAPPDATA}\Temp\
Final copy	New-Item -ItemType Directory -Force + Copy-Item + Remove-Item (temp cleanup)

The Base64 encoding step exists to safely pass arbitrary JSON (including quotes, backslashes, and Unicode) through the Windows command-line argument parser without escaping conflicts.

Sources: src/Concerns/WithWSL.php16-76

---

transformMcpCommandForWsl()

src/Concerns/WithWSL.php85-128

public function transformMcpCommandForWsl(string $command, array $args): array

Purpose: Convert the Linux-side $command / $args pair into a form that PhpStorm (running on Windows) can invoke via wsl.exe. PhpStorm's MCP client executes the command written in mcp.json as a Windows process; to run a command inside WSL it must call wsl.exe with appropriate flags.

Parameters

Parameter	Type	Description
$command	string	The incoming command (Sail path, wsl.exe, or a PHP binary path)
$args	array	The argument list accompanying the command

Return Value

array{command: string, args: array} — always returns an associative array with keys command and args.

Dispatch Logic (Three Cases)

Diagram: transformMcpCommandForWsl Branch Logic

Case Details

Case	Trigger Condition	Output command	Output args
1 — Sail	$command ends with /vendor/bin/sail (Unix) or \vendor\bin\sail (Windows)	"wsl.exe"	["--cd", base_path(), "./vendor/bin/sail", ...$args]
2 — Already wsl.exe	$command starts with "wsl"	$command (pass-through)	$args (pass-through)
3 — Direct PHP path	Any other value (e.g., /usr/bin/php, php)	"wsl.exe"	["--cd", base_path(), $command, ...$args]

The --cd flag instructs wsl.exe to change to the project directory before executing, which ensures relative paths (like ./vendor/bin/sail) resolve correctly.

Test Coverage

The test file tests/Feature/PhpStormCopilotTest.php92-202 covers all three cases and several path variants:

Test name	Case covered
transformMcpCommandForWsl handles Sail with relative path	Case 1 — ./vendor/bin/sail
transformMcpCommandForWsl handles Sail with absolute path	Case 1 — /home/user/project/vendor/bin/sail
transformMcpCommandForWsl handles Sail with Windows-style path	Case 1 — C:\...\vendor\bin\sail
transformMcpCommandForWsl handles WSL without Sail	Case 2 — wsl.exe
transformMcpCommandForWsl handles direct PHP path	Case 3 — /usr/bin/php
transformMcpCommandForWsl handles relative PHP path	Case 3 — php

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

---

Call Graph Within PhpStormCopilot

Diagram: How PhpStormCopilot::installFileMcp Delegates to WithWSL

Sources: src/PhpStormCopilot.php119-132 src/Concerns/WithWSL.php16-76 src/Concerns/WithWSL.php85-128

---

Dependencies

Dependency	Used in	Purpose
Illuminate\Support\Facades\Process	installMcpViaWsl	Executes wslvar and powershell.exe subprocesses
wslvar (from wslu package)	installMcpViaWsl	Reads Windows environment variables from within WSL
powershell.exe	installMcpViaWsl	Reads/writes files on the Windows filesystem
base_path()	transformMcpCommandForWsl	Provides the project root as an absolute Linux path for wsl.exe --cd
$this->mcpConfigKey()	installMcpViaWsl	The JSON key used to namespace the server entry ("servers")
$this->removeEmptyArrays()	installMcpViaWsl	Strips empty arrays before writing; defined on PhpStormCopilot

Sources: src/Concerns/WithWSL.php1-129