Mago is a Rust-based static binary for PHP code quality. It combines formatting, linting, static analysis and architectural enforcement under one toolchain with a shared parser and configuration file.

terminal
curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash
composer require --dev carthage-software/mago
mago init
mago format
mago lint
mago analyze
mago guard

The project has published stable 1.x releases since December 2025. Version 1.51.2 was current when the article was written. Mago is free and open source under the MIT or Apache 2.0 licenses.

PHP projects commonly combine PHP-CS-Fixer or PHP_CodeSniffer for style checks, PHPStan or Psalm for analysis, and tools such as Deptrac for dependency rules. Each package typically has its own configuration and process. Mago aims to reduce that stack and does not require a PHP runtime for its static binary.

The analyzer is available through `mago analyze`. It detects type errors, unused code and impossible conditions. It understands PHPStan and Psalm annotations, generics, conditional types and flow narrowing.

`mago lint` checks correctness, consistency and security with 190 rules in nine categories in version 1.51.2. Many findings can be fixed automatically. The formatter is deterministic, follows PER-CS by default and supports presets for psr-12, laravel and drupal. The setup section invokes it as `mago format`, while the tool description also names `mago fmt`.

The architectural guard has two parts. A perimeter guard restricts dependencies between layers. A structural guard applies conditions to classes and symbols, such as requiring controllers to be final and to follow a naming pattern. These functions cover use cases associated with Deptrac and PHPArkitect.

Mago also provides `mago cst`, which exposes its concrete syntax tree for parser debugging and custom-rule development. The documented forms are `mago cst src/Kernel.php`, `mago cst src/Kernel.php --tokens`, `mago cst src/Kernel.php --json` and `mago cst src/Kernel.php --names`.

The project’s own benchmark reports that Mago lints a codebase about 29 times faster than PHP-CS-Fixer. Its Rust implementation produces native code, and the pipeline runs in parallel across available CPU cores.

Installation is possible through the project’s shell installer or Composer. `mago init` detects the PHP version and source directories from `composer.json`, then creates `mago.toml`. The main workflow uses `mago format`, `mago lint`, `mago analyze` and `mago guard`. `mago config` displays the effective configuration, while `mago list-files` shows the files selected for analysis.

Mago uses TOML by default, with YAML and JSON also supported. A minimal configuration can define `version = "1"`, `php-version = "8.3"` and `[source]` with `paths = ["src", "tests"]`. TOML uses UTF-8, case-sensitive keys, tables introduced by headers and arrays of tables introduced with double brackets.

The global keys must come before the first table header. PHP namespaces need escaped backslashes in double-quoted strings, duplicate keys and tables are invalid, and `php-version` must be quoted because `8.3` would otherwise be read as a number. A TOML-aware editor such as VS Code with Even Better TOML can validate the file.

The configuration supports shared settings such as `threads`, `extends`, source includes and exclusions. The formatter accepts options including `print-width`, `use-tabs`, `tab-width`, `single-quote`, `trailing-comma` and exclusions. CI jobs can use `mago format --check`.

The linter supports framework integrations, baselines, `minimum-fail-level` and per-rule settings. Examples include Symfony and PHPUnit integrations, `no-else-clause` with a warning level, and `cyclomatic-complexity` with a configurable threshold. `mago lint --explain <rule>` provides details for a rule. The analyzer supports ignored checks, baselines, plugins and individually enabled strictness options.

Guard rules use TOML tables and arrays of tables. A perimeter can define layers such as `App\\Domain`, `App\\Application` and `App\\Infrastructure`, with permissions such as `@self` and `@native`. Structural rules can target `App\\Controller\\**` and require a final class with a `*Controller` name. Similar array-based rules can cover namespaces and symbols.

Mago can cover responsibilities handled by several established PHP tools, but it does not yet match their full plugin ecosystems or all framework-specific extensions. The recommended adoption path is to run it alongside existing checks, compare results and remove individual tools only after confirming coverage for the project.