Core Implementation

This document provides an overview of the core implementation components that enable the Laravel Boost PhpStorm Copilot package to bridge PhpStorm's GitHub Copilot plugin with Laravel Boost's MCP server. It covers the primary classes, their responsibilities, and how they interact to manage system-wide MCP configuration across multiple platforms.

For detailed information about specific components, see the sub-pages:

• PhpStormCopilot Agent Class (page 4.1) — inheritance chain, interface implementations, and all public methods
• Platform and Environment Detection (page 4.2) — systemDetectionConfig and projectDetectionConfig per OS
• MCP Configuration Generation (page 4.3) — installFileMcp dispatch logic, WSL branch, and Sail transformation
• Service Provider Registration (page 4.4) — PhpStormCopilotServiceProvider and Boost::registerAgent

Component Overview

The core implementation consists of three primary components that work together to provide cross-platform MCP configuration management:

Component	File	Primary Responsibility
PhpStormCopilot	src/PhpStormCopilot.php15	Main agent class that orchestrates platform detection, MCP configuration, and file management
WithWSL	src/Concerns/WithWSL.php9	Trait providing WSL-specific functionality for cross-boundary file operations and command transformation
PhpStormCopilotServiceProvider	src/PhpStormCopilotServiceProvider.php10	Laravel service provider that registers the agent with the Boost framework via Boost::registerAgent

Sources: src/PhpStormCopilot.php1-187 src/Concerns/WithWSL.php1-129 src/PhpStormCopilotServiceProvider.php1-21

Core Architecture

The following diagram illustrates how the core components relate to each other and their dependencies on Laravel Boost framework interfaces:

Diagram: Core Class Structure and Dependencies

Sources: src/PhpStormCopilot.php8-15 src/Concerns/WithWSL.php9

Interface Implementations

The PhpStormCopilot class implements three Laravel Boost framework interfaces, each serving a specific purpose:

SupportsGuidelines Interface

Provides AI coding guidelines to GitHub Copilot through markdown files. The guidelinesPath() method returns the location where Laravel Boost's compiled guidelines should be written.

Method: guidelinesPath()
Returns: .github/instructions/laravel-boost.instructions.md
Configured via: boost.agents.phpstorm_copilot.guidelines_path

Sources: src/PhpStormCopilot.php8-89

SupportsMcp Interface

Enables MCP (Model Context Protocol) server integration with PhpStorm's Copilot plugin. Three critical methods define MCP behavior:

Method	Return Value	Purpose
mcpConfigKey()	"servers"	Top-level key in mcp.json where server configurations are stored
mcpConfigPath()	Platform-specific path	System-wide location of mcp.json file
useAbsolutePathForMcp()	true	Forces absolute paths for PHP executables and artisan commands

Sources: src/PhpStormCopilot.php9-114

SupportsSkills Interface

Manages project-specific AI skills that enhance Copilot's capabilities. The skillsPath() method determines where skill files are written.

Method: skillsPath()
Returns: .github/skills
Configured via: boost.agents.phpstorm_copilot.skills_path

Sources: src/PhpStormCopilot.php10-97

Detection Configuration

The agent provides two types of detection configuration to enable Laravel Boost to identify when PhpStorm and GitHub Copilot are installed:

Diagram: Detection Configuration Flow

The systemDetectionConfig() method returns platform-specific paths where PhpStorm or GitHub Copilot might be installed, using a match expression on the Platform enum src/PhpStormCopilot.php39-67 The Linux paths also include WSL cross-filesystem paths such as /mnt/c/Users/*/AppData/Local/github-copilot. The projectDetectionConfig() method identifies Laravel projects configured for GitHub Copilot by checking for the presence of .github/copilot-instructions.md src/PhpStormCopilot.php74-79

Sources: src/PhpStormCopilot.php39-79

MCP Installation Flow

The installFileMcp() method orchestrates the MCP configuration installation process with platform-specific handling:

Diagram: MCP Installation Decision Flow

Key Decision Points:

1. Testbench Detection: Throws an exception if running in Orchestra Testbench environment src/PhpStormCopilot.php121-123
2. WSL Detection: Uses WithWSL::installMcpViaWsl() for cross-boundary file operations src/PhpStormCopilot.php125-127
3. Sail Transformation: Wraps Laravel Sail commands with bash -c before delegating to parent src/PhpStormCopilot.php129-132

Sources: src/PhpStormCopilot.php119-132

Command Transformation Strategy

The package implements two levels of command transformation to ensure proper execution across different environments:

Sail Command Transformation

The transformSailCommand() method handles Laravel Sail by wrapping commands with bash -c and explicitly changing to the project directory:

Transformation Logic:

Input: command = './vendor/bin/sail'
 args = ['artisan', 'boost:mcp']

Output: command = 'bash'
 args = ['-c', 'cd /absolute/path && ./vendor/bin/sail artisan boost:mcp']

This ensures the working directory is correct when PhpStorm invokes the command src/PhpStormCopilot.php141-162

Sources: src/PhpStormCopilot.php141-162

WSL Command Transformation

For WSL environments, the WithWSL::transformMcpCommandForWsl() method transforms commands to use wsl.exe with the --cd flag:

Diagram: WSL Command Transformation Cases

This three-case transformation ensures commands execute in the correct WSL directory when invoked from Windows PhpStorm src/Concerns/WithWSL.php85-128

Sources: src/Concerns/WithWSL.php85-128

Configuration Sanitization

The removeEmptyArrays() method recursively removes empty arrays from MCP configuration to prevent compatibility issues with some MCP tools that fail when encountering empty arrays like "headers": [].

Algorithm:

1. Iterate through all key-value pairs in the configuration array
2. For array values, recursively call removeEmptyArrays()
3. If the array is empty after recursion, unset it from the parent
4. Return the sanitized configuration

This method is called on the complete configuration before writing to mcp.json src/PhpStormCopilot.php168-181 and during WSL installation src/Concerns/WithWSL.php48

Sources: src/PhpStormCopilot.php168-181 src/Concerns/WithWSL.php48

Platform-Specific Path Resolution

The mcpConfigPath() method returns the system-wide location where PhpStorm's GitHub Copilot plugin reads its MCP configuration:

Platform	Path
Darwin (macOS)	~/.config/github-copilot/intellij/mcp.json
Linux	~/.config/github-copilot/intellij/mcp.json
Windows	%LOCALAPPDATA%\github-copilot\intellij\mcp.json

The method uses a match expression on Platform::current() to return the appropriate path src/PhpStormCopilot.php104-114

Sources: src/PhpStormCopilot.php104-114

WSL Cross-Boundary Operations

The WithWSL trait encapsulates all WSL-specific logic for operating across the Windows-Linux boundary:

Diagram: installMcpViaWsl — WSL File Writing Process

Key WSL Operations:

1. Path Resolution: Uses wslvar LOCALAPPDATA to get Windows environment variable src/Concerns/WithWSL.php19
2. File Reading: Reads existing mcp.json via PowerShell src/Concerns/WithWSL.php30-33
3. Command Transformation: Converts commands to wsl.exe format src/Concerns/WithWSL.php40
4. File Writing: Uses Base64 encoding to safely write JSON via PowerShell src/Concerns/WithWSL.php56-61
5. Atomic Move: Writes to temp file first, then moves to final location src/Concerns/WithWSL.php68-73

Sources: src/Concerns/WithWSL.php16-76

Design Decisions

Absolute Path Requirement

The useAbsolutePathForMcp() method returns true src/PhpStormCopilot.php29-32 forcing Laravel Boost to use absolute paths for PHP executables and artisan scripts. This is necessary because PhpStorm's Copilot plugin may invoke MCP commands from different working directories, so relative paths would fail.

Testbench Exclusion

The agent explicitly throws an exception when running in Orchestra Testbench src/PhpStormCopilot.php121-123 as Testbench provides a simulated Laravel environment that cannot properly integrate with PhpStorm's system-wide configuration. Users are directed to use laravel-boost-copilot-cli for testing purposes instead.

Configuration Key Structure

The mcpConfigKey() returns "servers" src/PhpStormCopilot.php99-102 which is the top-level key expected by PhpStorm's GitHub Copilot plugin MCP implementation. This differs from other MCP clients that may use different key structures.

Sources: src/PhpStormCopilot.php29-123