Mago: A Rust-Powered Ultra-Fast PHP Static Analyzer

What is Mago?

Mago (pronounced mah‑go) is a PHP static analysis toolchain written in Rust. Because it is compiled to a native binary, it runs without a PHP runtime or Composer and has no start‑up overhead.

Installation

The quickest way is the official install script:

curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash

Other options: Homebrew ( brew install mago), Composer, Docker, WinGet. Verify the installation with:

mago --version
1.45.0

A GitHub Action setup-mago is also available for CI pipelines.

Configuration

Run mago init to create mago.toml at the project root. The file defines scanned directories, target PHP version, and rule strictness. It is analogous to phpstan.neon or psalm.xml.

Linting

Execute mago lint to check correctness, consistency and clarity. Example PHP file:

<?php

function getUsername(User $user): string {
    if ($user->isActive()) {
        if ($user->isPremium()) {
            return '开源技术小栈';
        }
    }
    return 'Tinywan';
}

Sample output:

# warning[strict-types]: Missing `declare(strict_types=1);` statement at the beginning of the file.
…
help[function-name]: Function name `getUsername` should be in snake case.
…
warning: found 2 issues: 1 warning(s), 1 help message(s)

Safe automatic fixes can be applied with mago lint --fix. Unsafe fixes require --unsafe.

Bug Analysis

The analyzer builds a semantic model of the whole codebase, knows function return types, class properties, and thrown exceptions, and can spot logical impossibilities such as calling a non‑existent method on a type.

Running mago analyze finds type mismatches, dead code, and impossible logic. Example:

<?php
function totalItems(int $cartCount): int {
    return $cartCount . " 开源技术小栈";
}

Output:

error[invalid-return-statement]: Invalid return type for function `totalItems`: expected `int`, but found `truthy-string`.
…
help: Change the return value to match `int` or update the function return type declaration.

Code Formatting

Use mago fmt to apply deterministic formatting to the entire codebase.

./mago fmt test.php
INFO Successfully formatted 1 file.

All team members see the same style, eliminating formatting disputes.

Performance

On a 134 k‑line sub‑project, Mago completed analysis in about 3.4 seconds, whereas PHPStan plus PHP_CodeSniffer took roughly 13.9 seconds (8.2 s + 5.7 s), a speedup of 30‑58×.

Workflow Integration

Mago works well in CI/CD pipelines and pre‑commit hooks. It can be used alongside existing tools, but some PHPStan/Psalm rules are not yet implemented, so it is currently an additional fast feedback stage rather than a full replacement.

Precautions

Mago is still maturing; not every rule from PHPStan or Psalm is available. mago fmt rewrites files in place – commit changes first to review diffs.

The tool reads configuration only from mago.toml; existing phpstan.neon or psalm.xml are ignored.

Key Takeaways

Mago is a Rust‑written PHP static analysis toolchain. mago lint checks correctness, consistency and clarity. mago analyze captures type errors and dead code. mago fmt enforces code formatting.

It is faster than many established tools, though its rule set is still growing.