PhpStormCopilot Agent Class

Purpose and Scope

This document provides technical documentation for the PhpStormCopilot class, which serves as the primary agent implementation for integrating Laravel Boost with PhpStorm's GitHub Copilot plugin. The class extends Laravel Boost's Agent base class and implements three interfaces that provide guidelines, MCP server configuration, and skills management capabilities.

This page focuses on the class structure, method signatures, and responsibilities. For platform-specific detection logic, see page 4.2. For MCP configuration file generation, see page 4.3. For WSL-specific implementation details, see page 5.3. For Laravel Sail command handling, see page 5.4.

Sources: src/PhpStormCopilot.php1-187

---

Class Architecture

The PhpStormCopilot class is defined in the Revolution\Laravel\Boost namespace and serves as the bridge between Laravel Boost's agent system and PhpStorm's GitHub Copilot plugin.

Inheritance and interface map for PhpStormCopilot:

Sources: src/PhpStormCopilot.php1-17 src/Concerns/WithWSL.php1-14

---

Class Declaration and Dependencies

The class declaration establishes the inheritance hierarchy and interface contracts:

Component	Type	Source
Agent	Parent class	Laravel\Boost\Install\Agents\Agent
SupportsGuidelines	Interface	Laravel\Boost\Contracts\SupportsGuidelines
SupportsMcp	Interface	Laravel\Boost\Contracts\SupportsMcp
SupportsSkills	Interface	Laravel\Boost\Contracts\SupportsSkills
WithWSL	Trait	Revolution\Laravel\Boost\Concerns\WithWSL

Sources: src/PhpStormCopilot.php8-17

---

Identity Methods

name()

Returns the internal identifier used to register this agent with Laravel Boost.

public function name(): string

Returns: 'phpstorm-copilot'

This identifier is used in configuration files, command output, and agent registry lookups.

Sources: src/PhpStormCopilot.php19-22 tests/Feature/PhpStormCopilotTest.php8-13

displayName()

Returns the human-readable name shown in CLI output and error messages.

public function displayName(): string

Returns: 'PhpStorm with GitHub Copilot'

Sources: src/PhpStormCopilot.php24-27 tests/Feature/PhpStormCopilotTest.php15-20

useAbsolutePathForMcp()

Indicates that this agent requires absolute paths in MCP configuration.

public function useAbsolutePathForMcp(): bool

Returns: true

PhpStorm's Copilot plugin requires absolute paths because the system-wide mcp.json file cannot resolve relative paths correctly when invoked from the IDE.

Sources: src/PhpStormCopilot.php29-32

---

Detection Configuration Methods

Detection method dispatch by Platform enum value:

Sources: src/PhpStormCopilot.php39-79

systemDetectionConfig()

Provides platform-specific paths for detecting PhpStorm and GitHub Copilot installation.

public function systemDetectionConfig(Platform $platform): array

Parameters:

• $platform: An enum value from Laravel\Boost\Install\Enums\Platform (Darwin, Linux, or Windows)

Returns: Array with structure ['paths' => string[]]

Platform	Detection Paths
Darwin	~/Library/Application Support/JetBrains/PhpStorm*/plugins/github-copilot-intellij /Applications/PhpStorm.app
Linux	/opt/phpstorm, /opt/PhpStorm* /usr/local/bin/phpstorm ~/.local/share/JetBrains/Toolbox/apps/PhpStorm/ch-* /mnt/c/Users/*/AppData/Local/github-copilot (WSL)
Windows	%LOCALAPPDATA%\github-copilot\intellij %ProgramFiles%\JetBrains\PhpStorm* %LOCALAPPDATA%\JetBrains\Toolbox\apps\PhpStorm\ch-* %LOCALAPPDATA%\Programs\PhpStorm

The Linux platform includes /mnt/c/Users/*/AppData/Local/github-copilot to detect WSL environments where PhpStorm runs on Windows.

Sources: src/PhpStormCopilot.php39-67 tests/Feature/PhpStormCopilotTest.php29-47

projectDetectionConfig()

Defines how to detect if the current Laravel project is configured for PhpStorm Copilot.

public function projectDetectionConfig(): array

Returns: Array with structure ['files' => string[]]

The method checks for the existence of .github/copilot-instructions.md, which indicates that the project has been configured with PhpStorm-specific Copilot instructions.

Sources: src/PhpStormCopilot.php74-79 tests/Feature/PhpStormCopilotTest.php49-57

---

Path Configuration Methods

guidelinesPath()

Returns the file path where AI guidelines should be written for PhpStorm Copilot.

public function guidelinesPath(): string

Returns: .github/instructions/laravel-boost.instructions.md (default) or value from config('boost.agents.phpstorm_copilot.guidelines_path')

This path is used by Laravel Boost to write AI guidelines that GitHub Copilot reads when providing code suggestions.

Sources: src/PhpStormCopilot.php86-89

skillsPath()

Returns the directory path where agent skills should be written.

public function skillsPath(): string

Returns: .github/skills (default) or value from config('boost.agents.phpstorm_copilot.skills_path')

Skills are specialized instruction sets that enhance Copilot's capabilities for specific tasks like Pest testing.

Sources: src/PhpStormCopilot.php93-97

---

MCP Configuration Methods

mcpConfigKey() and mcpConfigPath() and the resulting mcp.json structure:

Sources: src/PhpStormCopilot.php99-114

mcpConfigKey()

Returns the top-level JSON key under which MCP server configurations are stored.

public function mcpConfigKey(): string

Returns: 'servers'

PhpStorm's Copilot plugin expects MCP servers to be defined under the servers key in mcp.json.

Sources: src/PhpStormCopilot.php99-102 tests/Feature/PhpStormCopilotTest.php22-27

mcpConfigPath()

Returns the platform-specific absolute path to the system-wide MCP configuration file.

public function mcpConfigPath(): string

Returns: Platform-specific path:

• Darwin/Linux: ~/.config/github-copilot/intellij/mcp.json
• Windows: %LOCALAPPDATA%\github-copilot\intellij\mcp.json

The method detects the current platform using Platform::current() and returns the appropriate path. On Linux, it uses the HOME environment variable; on Windows, it uses the LOCALAPPDATA environment variable placeholder.

Sources: src/PhpStormCopilot.php104-114

---

Command Transformation

transformSailCommand()

Transforms Laravel Sail commands to ensure proper working directory context when executed by PhpStorm.

transformSailCommand decision flow:

Sources: src/PhpStormCopilot.php141-162

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

Parameters:

• $command: The command path (e.g., ./vendor/bin/sail or absolute PHP path)
• $args: Command arguments (e.g., ["artisan", "boost:mcp"])

Returns: Array with structure ['command' => string, 'args' => array]

Behavior:

1. Non-Sail commands: Returns the command and args unchanged
2. Sail commands: Wraps the command in bash -c to ensure the working directory is correct

Example transformation:

Input Command	Input Args	Output Command	Output Args
./vendor/bin/sail	["artisan", "boost:mcp"]	bash	["-c", "cd /path/to/project && ./vendor/bin/sail artisan boost:mcp"]
/usr/bin/php	["artisan", "boost:mcp"]	/usr/bin/php	["artisan", "boost:mcp"]

The transformation is necessary because PhpStorm may invoke MCP commands from a different working directory, and Sail requires execution from the project root to find the docker-compose.yml file.

Sources: src/PhpStormCopilot.php141-162 tests/Feature/PhpStormCopilotTest.php92-202

---

Protected Methods

installFileMcp()

Protected method that handles the installation of MCP configuration to the system-wide location.

protected function installFileMcp(string $key, string $command, array $args = [], array $env = []): bool

Parameters:

• $key: Server name key (e.g., 'laravel-boost')
• $command: The command to execute (e.g., PHP binary path or ./vendor/bin/sail)
• $args: Command arguments (e.g., ["artisan", "boost:mcp"])
• $env: Environment variables (optional)

Returns: true on success, throws Exception on failure

Flow:

installFileMcp dispatch sequence:

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

Special Cases:

1. Testbench Environment: Throws an exception suggesting the use of laravel-boost-copilot-cli instead, as Testbench lacks the proper environment context for system-wide MCP configuration
2. WSL Environment: Delegates to installMcpViaWsl() from the WithWSL trait
3. Native/Sail Environment: Applies Sail command transformation before calling parent implementation

Sources: src/PhpStormCopilot.php119-132

removeEmptyArrays()

Recursively removes empty arrays from configuration data to ensure MCP compatibility.

protected function removeEmptyArrays(array $data): array

Parameters:

• $data: Configuration array to sanitize

Returns: Sanitized array with all empty arrays removed

Purpose: Some MCP tools fail when encountering empty arrays in the configuration (e.g., "headers": []). This method recursively traverses the configuration and removes any empty array values.

Example:

// Input
[
 'command' => 'wsl.exe',
 'args' => ['php', 'artisan', 'boost:mcp'],
 'env' => [],
 'headers' => []
]

// Output
[
 'command' => 'wsl.exe',
 'args' => ['php', 'artisan', 'boost:mcp']
]

Sources: src/PhpStormCopilot.php168-181

isRunningInTestbench()

Checks if the code is running in Orchestra Testbench environment.

protected function isRunningInTestbench(): bool

Returns: true if the TESTBENCH_CORE constant is defined, false otherwise

This detection prevents the package from attempting system-wide MCP configuration during tests, which would fail due to missing environment context.

Sources: src/PhpStormCopilot.php183-186

---

Method Summary Table

Method	Visibility	Return Type	Purpose
name()	public	string	Returns agent identifier: 'phpstorm-copilot'
displayName()	public	string	Returns human-readable name
useAbsolutePathForMcp()	public	bool	Indicates requirement for absolute paths
systemDetectionConfig()	public	array	Platform-specific detection paths
projectDetectionConfig()	public	array	Project-level detection configuration
guidelinesPath()	public	string	Path to AI guidelines file
skillsPath()	public	string	Path to skills directory
mcpConfigKey()	public	string	Top-level JSON key for MCP config
mcpConfigPath()	public	string	Platform-specific MCP config file path
transformSailCommand()	public	array	Wraps Sail commands in bash -c
installFileMcp()	protected	bool	Installs MCP configuration
removeEmptyArrays()	protected	array	Sanitizes config by removing empty arrays
isRunningInTestbench()	protected	bool	Detects Testbench environment

Sources: src/PhpStormCopilot.php1-187

---

Trait Integration

The class uses the WithWSL trait to add WSL-specific functionality:

Trait Method	Purpose
isWSL()	Detects if running in WSL environment
installMcpViaWsl()	Handles MCP installation via PowerShell for WSL
transformMcpCommandForWsl()	Transforms commands for cross-boundary execution

For detailed documentation of these methods, see WSL (Windows Subsystem for Linux) and WithWSL Trait API.

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