Getting Started

Purpose and Scope: This document guides you through installing and configuring the revolution/laravel-boost-phpstorm-copilot package. It covers system requirements, the initial installation process via composer, the interactive boost:install configuration command, and the critical architectural constraint of system-wide MCP configuration that affects multi-project workflows. For detailed platform-specific implementations (WSL, Sail, etc.), see Platform-Specific Implementations. For internal component details, see Core Implementation. For development and contributing, see Development Guide.

---

Prerequisites and System Requirements

The package requires specific versions of PHP, Laravel, and Laravel Boost, plus the GitHub Copilot plugin in PhpStorm.

Required Software

Component	Minimum Version	Purpose
PHP	8.3	Runtime for artisan commands and MCP server
Laravel	12.x	Framework dependency
Laravel Boost	2.0	Provides MCP server foundation and agent registration
PhpStorm	Latest	IDE for development
GitHub Copilot Plugin	Latest	Connects to MCP server via mcp.json

Supported Platforms

The package detects and adapts to five distinct execution environments:

Platform-Specific Requirements:

• macOS/Linux/Windows: No additional requirements
• WSL: Requires wslu package (sudo apt install wslu). Verify with wslvar -v
• Sail: Start containers before running boost:install with vendor/bin/sail up -d

Sources: README.md7-33

---

Installation Process

Step 1: Install via Composer

Install the package as a development dependency:

The package uses Laravel's auto-discovery mechanism via PhpStormCopilotServiceProvider to register with the framework automatically.

Step 2: Verify Installation

After installation, verify the package is registered:

You should see PhpStorm with GitHub Copilot appear in the agent selection list when you run the installation command.

Installation Flow Diagram:

Sources: README.md90-94 src/PhpStormCopilotServiceProvider.php

---

Initial Configuration with boost:install

The php artisan boost:install command provides an interactive wizard that configures three distinct capabilities.

Interactive Configuration Wizard

When you run boost:install, you'll encounter two selection prompts:

Prompt 1: Feature Selection

Which Boost features would you like to configure?

Feature Option	Output	Purpose
AI Guidelines	.github/instructions/laravel-boost.instructions.md	Project-specific AI coding guidelines
Agent Skills	.github/skills/ directory	Reusable skills like pest-testing
Boost MCP Server Configuration	Platform-specific mcp.json	Connects Copilot to your project's MCP server

Prompt 2: Agent Selection

Which AI agents would you like to configure?

Select PhpStorm with GitHub Copilot (not "PhpStorm" which refers to PhpStorm Junie, a different agent).

Configuration Flow

Example: Standard Installation

Interactive selections:

1. Select all features: AI Guidelines, Agent Skills, Boost MCP Server Configuration
2. Select agent: PhpStorm with GitHub Copilot

Result: Creates three artifacts:

• .github/instructions/laravel-boost.instructions.md (guidelines)
• .github/skills/pest-testing/ (testing skill definitions)
• Platform-specific mcp.json with absolute paths to your project

Sources: README.md96-111 src/PhpStormCopilot.php

---

Understanding the System-Wide MCP Configuration Constraint

The most critical architectural limitation of this package is that mcp.json is stored in a system-wide location but contains project-specific absolute paths.

The Constraint Explained

MCP Configuration Structure

The generated mcp.json contains absolute paths:

Key Points:

• command: Absolute path to PHP binary (e.g., /usr/bin/php, C:\php\php.exe)
• args[0]: Absolute path to current project's artisan file
• args[1]: The boost:mcp command that starts the MCP server

Why This Matters

Scenario	Configuration State	Result
Working on Project A	mcp.json points to /home/user/projectA/artisan	✅ Copilot provides Project A context
Switch to Project B without reconfiguring	mcp.json still points to /home/user/projectA/artisan	❌ Copilot provides wrong project context
Switch to Project B and run boost:install	mcp.json updated to /home/user/projectB/artisan	✅ Copilot provides Project B context

Sources: README.md113-125 src/PhpStormCopilot.php

---

Multi-Project Workflow

Working with multiple Laravel projects requires updating the mcp.json configuration each time you switch projects.

Required Workflow

Step-by-Step: Switching Projects

Scenario: You're working on projectA and need to switch to projectB.

Step 1: Navigate to new project

Step 2: Reconfigure MCP for this project

Explanation of flags:

• --guidelines: Update AI guidelines for this project
• --skills: Update agent skills for this project
• --mcp: Update MCP configuration (most critical)
• --no-interaction: Skip prompts, use defaults

Step 3: Verify configuration

Verify the args[0] path points to the current project's artisan file.

Alternative: Project-Level Configuration

For developers who frequently switch projects, consider using laravel-boost-copilot-cli which supports project-level MCP configuration files, eliminating the need for manual reconfiguration.

Sources: README.md113-121

---

Troubleshooting Common Issues

Issue 1: WSL Interoperability Disabled

Symptom: Error message: [error] WSL Interoperability is disabled. Please enable it before using WSL.

Solution: Enable WSL Interop via binfmt configuration:

Issue 2: wslvar Command Not Found (WSL)

Symptom: boost:install fails with command not found error for wslvar

Diagnosis:

Solution: Install wslu package:

Verification:

Issue 3: PowerShell Access Denied (WSL)

Symptom: MCP configuration file not created in Windows from WSL

Diagnosis:

Solution: Ensure PowerShell is accessible from WSL. Check that Windows Defender or antivirus is not blocking WSL→Windows file operations.

Issue 4: Wrong Project Context in Copilot

Symptom: Copilot suggests code from a different project

Cause: mcp.json points to wrong project's artisan file

Solution: Re-run installation in current project:

Issue 5: MCP Config File Not Found

Symptom: Copilot doesn't connect to MCP server

Diagnosis by Platform:

Solution:

1. Verify parent directory exists and is writable
2. Re-run boost:install --mcp
3. For WSL: Ensure user profile is on C drive (default location)

Issue 6: Laravel Sail Commands Not Working

Symptom: MCP server doesn't start with Sail

Diagnosis:

Solution: Start Sail before running boost:install:

Diagnostic Command Reference

Environment	Verification Command	Expected Output
WSL Detection	echo $WSL_DISTRO_NAME	Distribution name (e.g., Ubuntu)
WSL Interop	powershell.exe -Command "Write-Output 'test'"	test
wslvar	wslvar LOCALAPPDATA	C:\Users\YourUsername\AppData\Local
PHP Path	which php or where php	Absolute PHP binary path
Artisan Path	ls -la artisan	Artisan file in project root
Sail Status	vendor/bin/sail ps	Running container list
MCP Config (Unix)	cat ~/.config/github-copilot/intellij/mcp.json	JSON configuration
MCP Config (Windows)	type %LOCALAPPDATA%\github-copilot\intellij\mcp.json	JSON configuration

Advanced Troubleshooting

For environment-specific issues:

• WSL details: See WSL (Windows Subsystem for Linux)
• Sail integration: See Laravel Sail Integration
• Platform detection: See Environment Detection System

Sources: README.md35-60 README.md113-125 src/Concerns/WithWSL.php

---

Next Steps

After completing initial setup:

1. Verify Configuration: Open PhpStorm and trigger GitHub Copilot. It should now have access to your Laravel project context via the MCP server.

2. Understand AI Capabilities: See AI Guidelines and Skills for details on configured guidelines and testing skills.

3. Learn Multi-Project Management: Bookmark the non-interactive installation command for quick project switching:

4. Explore Platform-Specific Features: If using WSL or Sail, review Platform-Specific Implementations for advanced configuration options.

5. Customize Guidelines: Edit .github/instructions/laravel-boost.instructions.md to add project-specific AI guidelines.

Sources: README.md96-128