Mago est un binaire statique consacré à la qualité du code PHP, développé en Rust. Il réunit le formatage, le linting, l’analyse statique et le contrôle architectural avec un parseur et une configuration partagés.

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

Le projet publie des versions stables 1.x depuis décembre 2025. La version 1.51.2 était la version courante au moment de l’article. Mago est un logiciel libre sous licence MIT ou Apache 2.0.

Dans un projet PHP courant, PHP-CS-Fixer ou PHP_CodeSniffer vérifie le style, PHPStan ou Psalm effectue l’analyse, et des outils comme Deptrac contrôlent les dépendances. Chaque composant possède généralement sa configuration et son propre processus. Le binaire statique de Mago fonctionne sans runtime PHP pour exécuter ces contrôles.

L’analyseur est lancé avec `mago analyze`. Il repère les erreurs de type, le code inutilisé et les conditions impossibles. Il prend en charge les annotations PHPStan et Psalm, les génériques, les types conditionnels et le flow narrowing.

`mago lint` vérifie la correction, la cohérence et la sécurité. La version 1.51.2 contient 190 règles réparties dans neuf catégories. Plusieurs diagnostics peuvent être corrigés automatiquement. Le formateur produit un résultat déterministe et suit PER-CS par défaut. Des presets existent pour psr-12, laravel et drupal. La section d’installation emploie `mago format`, tandis que la description de l’outil mentionne aussi `mago fmt`.

Le contrôle architectural comporte deux volets. Le perimeter guard limite les dépendances entre couches. Le structural guard impose des propriétés aux classes et aux symboles, par exemple des contrôleurs finaux suivant une convention de nommage. Ces fonctions couvrent des usages associés à Deptrac et PHPArkitect.

La commande `mago cst` expose le Concrete Syntax Tree pour déboguer le parseur et développer des règles personnalisées. Les formes documentées sont `mago cst src/Kernel.php`, `mago cst src/Kernel.php --tokens`, `mago cst src/Kernel.php --json` et `mago cst src/Kernel.php --names`.

Selon le benchmark publié par le projet, Mago lint une base de code environ 29 fois plus vite que PHP-CS-Fixer. Rust produit du code natif. Le pipeline travaille en parallèle sur les cœurs CPU disponibles.

L’installation passe par le script shell du projet ou par Composer. `mago init` récupère la version de PHP et les répertoires sources dans `composer.json`, puis crée `mago.toml`. Le flux principal utilise `mago format`, `mago lint`, `mago analyze` et `mago guard`. `mago config` affiche la configuration effective. `mago list-files` indique les fichiers retenus pour l’analyse.

Mago utilise TOML par défaut, mais accepte aussi YAML et JSON. Une configuration minimale peut définir `version = "1"`, `php-version = "8.3"` et, dans `[source]`, `paths = ["src", "tests"]`. TOML utilise l’UTF-8 et des clés sensibles à la casse. Les tables commencent par un en-tête et les tableaux de tables par des doubles crochets.

Les clés globales doivent apparaître avant le premier en-tête de table. Les antislashs des namespaces PHP doivent être doublés dans les chaînes entre guillemets doubles. Les clés et tables dupliquées provoquent une erreur. `php-version` doit être une chaîne, car `8.3` serait interprété comme un nombre. VS Code et l’extension Even Better TOML peuvent valider le fichier.

Les options globales comprennent `threads`, `extends`, les inclusions de sources et les exclusions. Le formateur propose notamment `print-width`, `use-tabs`, `tab-width`, `single-quote`, `trailing-comma` et des exclusions. La commande `mago format --check` permet de contrôler le formatage en CI.

Le linter accepte des intégrations de frameworks, des baselines, `minimum-fail-level` et des paramètres par règle. Les exemples citent les intégrations Symfony et PHPUnit, `no-else-clause` avec le niveau warning et `cyclomatic-complexity` avec un seuil configurable. `mago lint --explain <rule>` donne le détail d’une règle. L’analyseur prend en charge les exclusions, les baselines, les plugins et l’activation progressive de contrôles plus stricts.

Les règles du guard utilisent des tables et des tableaux de tables TOML. Un périmètre peut définir les couches `App\\Domain`, `App\\Application` et `App\\Infrastructure`, avec des autorisations comme `@self` et `@native`. Une règle structurelle peut viser `App\\Controller\\**` et exiger une classe finale nommée `*Controller`. Des règles similaires peuvent cibler des namespaces et des symboles.

Mago couvre une partie des responsabilités de plusieurs outils PHP établis. Il ne possède pas encore toute leur richesse de plugins ni toutes leurs extensions propres aux frameworks. L’article conseille donc de l’exécuter d’abord avec les outils existants, de comparer les résultats et de retirer chaque composant seulement après validation de la couverture du projet.