Mago (Unofficial) - VS Code Extension

Unofficial VS Code extension for Mago PHP analyzer - Get instant code analysis, quick fixes, and intelligent diagnostics directly in your editor.

🚀 Features

⚡ Real-time Analysis

Workspace-wide analysis on startup, save, or as you type
Instant diagnostics with precise error highlighting
Auto-discovery of Mago binary from Composer
Performance optimized with smart re-analysis

🔧 Smart Quick Fixes

One-click fixes for common issues
Safety gating for potentially unsafe suggestions
Configurable safety levels (Safe, Potentially Unsafe, Unsafe)
Intelligent code suggestions from Mago

🎯 Issue Suppression

Line-level suppression with @mago-expect and @mago-ignore
Block-level suppression for code blocks
Workspace-wide suppression via mago.toml
Configurable visibility for each suppression type

🛠️ Commands

Command	Description	Shortcut
`Mago: Analyze Workspace`	Run analysis on entire workspace	-
`Mago: Analyze Current File`	Run analysis on current file	-

⚙️ Configuration

Core Settings

Setting	Description	Default
`mago.path`	Path to Mago binary (blank = auto-detect)	`""`
`mago.runOn`	When to run analysis	`save`
`mago.debounceMs`	Debounce delay for on-type analysis	`400`
`mago.minimumFailLevel`	Minimum issue level to show	`error`

Analysis Settings

Setting	Description	Default
`mago.analysis.apply.allowUnsafe`	Allow unsafe suggestions	`false`
`mago.analysis.apply.allowPotentiallyUnsafe`	Allow potentially unsafe suggestions	`false`

Suppression Settings

Setting	Description	Default
`mago.analysis.suppress.showLineExpect`	Show line-level expect actions	`true`
`mago.analysis.suppress.showLineIgnore`	Show line-level ignore actions	`true`
`mago.analysis.suppress.showBlockIgnore`	Show block-level ignore actions	`true`
`mago.analysis.suppress.showBlockExpect`	Show block-level expect actions	`true`
`mago.analysis.suppress.showWorkspaceIgnore`	Show workspace ignore actions	`true`

📋 Requirements

Mago CLI installed and available
PHP project with Composer (recommended)
VS Code 1.103.0 or higher

🚀 Quick Start

Install the extension from the VS Code Marketplace
Ensure Mago is installed in your project:
```
composer require --dev mago/mago
```
Create a mago.toml file in your project root (extension will help you create one)
Start coding! The extension will automatically analyze your PHP files

📁 Project Structure

your-project/
├── mago.toml          # Mago configuration
├── vendor/
│   └── bin/
│       └── mago       # Mago binary (auto-detected)
└── src/
    └── your-php-files.php

🔍 How It Works

Analysis Trigger: Extension runs Mago analysis based on your mago.runOn setting
Issue Detection: Mago scans your PHP code for issues and violations
Diagnostic Display: Issues appear as squiggles in the editor and in the Problems panel
Quick Fixes: Click the lightbulb icon to apply suggested fixes
Suppression: Use code actions to suppress specific issues

🎛️ Analysis Modes

On Save (default): Analyzes when you save files
On Type: Analyzes as you type (with debouncing)
Manual: Only analyzes when you run commands

🛡️ Safety Features

Vendor Filtering: Third-party code is analyzed but not shown in Problems
Safety Gating: Unsafe suggestions are disabled by default
Configurable Levels: Choose which safety levels to allow

🐛 Troubleshooting

Common Issues

Extension not working?

Check if Mago is installed: composer show mago/mago
Verify mago.toml exists in project root
Check the Output panel for error messages

Analysis not running?

Ensure mago.runOn is set correctly
Check if Mago binary path is correct
Try running "Mago: Analyze Workspace" manually

Too many issues?

Adjust mago.minimumFailLevel setting
Use suppression actions to hide specific issues
Configure mago.toml to exclude directories

📚 Learn More

Mago Documentation - Official Mago analyzer docs
VS Code Extension API - VS Code extension development
PHP Best Practices - PHP coding standards

🤝 Contributing

This is an unofficial extension. For issues and feature requests, please visit the GitHub repository.

📄 License

This extension is licensed under the MIT License. The Mago PHP analyzer is also licensed under the MIT License.

See LICENSE file for details.

Made with ❤️ for the PHP community

Mago (Unofficial)

kgz