Mago (Unofficial) - VS Code Extension

September 28, 2025 · View on GitHub

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)
- Use the provided schema for IntelliSense and validation
- See mago.toml.example for a complete configuration example
Start coding! The extension will automatically analyze your PHP files

📁 Project Structure

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

📋 Configuration Schema

The extension includes a comprehensive JSON schema for mago.toml files that matches the official Mago configuration format:

IntelliSense support - Auto-completion and validation in VS Code
Type checking - Validates PHP versions, paths, and configuration options
Documentation - Inline help for all configuration options
Examples - Real-world configuration examples

Configuration Structure:

# Global Options
php-version = "8.4"
threads = 8
stack-size = 8388608

[source]
paths = ["src", "tests"]
excludes = ["vendor/", "cache/"]
extensions = ["php", "php8"]

[linter]
# Linter-specific options

[formatter] 
# Formatter-specific options

[analyzer]
# Analyzer-specific options

To use the schema, add this to your mago.toml file:

#:schema https://raw.githubusercontent.com/kgz/mago_vscode/v0/mago.toml.schema.json

🔍 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