Laravel Sail Integration

This page documents how the laravel-boost-phpstorm-copilot package detects and handles Laravel Sail as the PHP execution environment, covering the two transformation methods and their behavior across non-WSL and WSL contexts.

For details on the general MCP installation flow (including the Testbench guard and how the parent class writes mcp.json), see 4.3. For WSL-specific behavior that is independent of Sail, see 5.3.

---

Why Sail Requires Special Handling

The MCP configuration file (mcp.json) records a command and args that PhpStorm's GitHub Copilot plugin runs as a subprocess at startup. For standard PHP projects, this is simply an absolute path to the php binary followed by the artisan path.

Laravel Sail is a Docker-based environment. The ./vendor/bin/sail script must be executed from within the project directory because it uses a relative docker-compose.yml reference. When the GitHub Copilot plugin spawns the MCP subprocess, it does not necessarily set the working directory to the project root. A bare ./vendor/bin/sail artisan boost:mcp will therefore fail unless the shell is first cd-ed to the project root.

Additionally, Sail uses a relative path (./vendor/bin/sail), which cannot be resolved unless the current directory is known.

---

Sail Detection

Sail detection is performed in transformSailCommand inside PhpStormCopilot and transformMcpCommandForWsl inside WithWSL. Both methods use the same detection condition: checking whether the $command string ends with /vendor/bin/sail.

Detection patterns accepted as Sail:

Pattern	Example	Matches?
Relative path	./vendor/bin/sail	Yes
Absolute Linux path	/home/user/project/vendor/bin/sail	Yes
Absolute Windows path	C:\Users\user\project\vendor\bin\sail	Yes (using \vendor\bin\sail)
PHP binary	/usr/bin/php	No
wsl.exe	wsl.exe	No

Sources: src/PhpStormCopilot.php144-149 src/Concerns/WithWSL.php88-102

---

Non-WSL Sail: transformSailCommand

Diagram: transformSailCommand Decision Flow

Sources: src/PhpStormCopilot.php141-162

When installFileMcp is called outside WSL, it first calls transformSailCommand. If a Sail path is detected, the method wraps the entire invocation in a bash -c call:

• command becomes bash
• args becomes ["-c", "cd /absolute/project/path && ./vendor/bin/sail artisan boost:mcp"]

The resulting mcp.json entry looks like:

The base_path() call at src/PhpStormCopilot.php152 ensures the path is always absolute. Each argument in $args is processed through escapeshellarg before being embedded in the shell string.

If the command is not Sail-related, transformSailCommand returns the command and args unchanged.

Sources: src/PhpStormCopilot.php141-162

---

WSL + Sail: transformMcpCommandForWsl

When the environment is WSL (isWSL() returns true), the installFileMcp method routes through installMcpViaWsl in the WithWSL trait. Inside that method, transformMcpCommandForWsl is called to adapt the command for PhpStorm running on the Windows host.

In the WSL + Sail scenario, PhpStorm on Windows must invoke Sail inside WSL. The tool for this is wsl.exe, which supports --cd to set the working directory inside the WSL filesystem before executing the command.

Diagram: transformMcpCommandForWsl Branching Logic

Sources: src/Concerns/WithWSL.php85-128

For the Sail case, the resulting mcp.json entry (on the Windows filesystem) looks like:

The --cd flag instructs wsl.exe to change to the given directory inside WSL before executing. The relative ./vendor/bin/sail then resolves correctly against the project root.

Note that both relative (./vendor/bin/sail) and absolute paths (e.g., /home/user/project/vendor/bin/sail) to Sail are normalized: in the WSL case, the output always uses the relative ./vendor/bin/sail with --cd providing the directory context.

Sources: src/Concerns/WithWSL.php88-102 tests/Feature/PhpStormCopilotTest.php92-147

---

Full Dispatch Flow: Sail in Context

Diagram: installFileMcp Dispatch Including Sail and WSL Branches

Sources: src/PhpStormCopilot.php119-162 src/Concerns/WithWSL.php16-128

---

Method Locations Summary

Method	Class / Trait	File	Purpose
installFileMcp	PhpStormCopilot	src/PhpStormCopilot.php	Top-level dispatch; routes to WSL or Sail transform
transformSailCommand	PhpStormCopilot	src/PhpStormCopilot.php	Wraps Sail in bash -c cd && sail for non-WSL
isWSL	WithWSL	src/Concerns/WithWSL.php	Checks WSL_DISTRO_NAME env var
installMcpViaWsl	WithWSL	src/Concerns/WithWSL.php	Full WSL write pipeline using PowerShell
transformMcpCommandForWsl	WithWSL	src/Concerns/WithWSL.php	Adapts any command (including Sail) for wsl.exe

Sources: src/PhpStormCopilot.php119-162 src/Concerns/WithWSL.php1-129

---

Prerequisite: Starting Sail Before Installation

Because mcp.json records a command that invokes Sail at runtime, Sail must be running when the GitHub Copilot plugin spawns the MCP subprocess. The README notes:

Before use, start it with vendor/bin/sail up -d.

boost:install itself does not start Sail. The transformSailCommand and transformMcpCommandForWsl methods only modify the recorded command and arguments; they do not validate that Docker or Sail is active at install time.

Sources: README.md21-23

---

Test Coverage

The test file tests/Feature/PhpStormCopilotTest.php covers transformMcpCommandForWsl for all Sail path variants:

Test name	Input command	Expected output command
handles Sail with relative path	./vendor/bin/sail	wsl.exe with --cd
handles Sail with absolute path	/home/user/project/vendor/bin/sail	wsl.exe with --cd
handles Sail with Windows-style path	C:\...\vendor\bin\sail	wsl.exe with --cd
handles WSL without Sail	wsl.exe	wsl.exe (pass-through)
handles direct PHP path	/usr/bin/php	wsl.exe with --cd
handles relative PHP path	php	wsl.exe with --cd

Sources: tests/Feature/PhpStormCopilotTest.php92-202