Mago ist ein statisches Binary für die PHP-Codequalität, das in Rust entwickelt wird. Das Tool bündelt Formatierung, Linting, statische Analyse und Architekturregeln mit einem gemeinsamen Parser und einer gemeinsamen Konfiguration.

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

Seit Dezember 2025 erscheinen stabile 1.x-Versionen. Zum Zeitpunkt des Artikels war Version 1.51.2 aktuell. Mago ist freie Open-Source-Software unter der MIT- oder Apache-2.0-Lizenz.

Typische PHP-Projekte kombinieren PHP-CS-Fixer oder PHP_CodeSniffer für Stilprüfungen, PHPStan oder Psalm für Analysen und Werkzeuge wie Deptrac für Abhängigkeitsregeln. Jedes Paket bringt meist eine eigene Konfiguration und einen eigenen Prozess mit. Das statische Mago-Binary benötigt zur Ausführung der Werkzeuge keine PHP-Laufzeit.

Der Analysator läuft mit `mago analyze`. Er findet Typfehler, ungenutzten Code und unmögliche Bedingungen. Unterstützt werden Annotationen von PHPStan und Psalm, Generics, bedingte Typen und Flow-Narrowing.

`mago lint` prüft Korrektheit, Konsistenz und Sicherheit. Version 1.51.2 enthält 190 Regeln in neun Kategorien. Viele Befunde lassen sich automatisch korrigieren. Der Formatter arbeitet deterministisch und folgt standardmäßig PER-CS. Für psr-12, laravel und drupal gibt es Presets. Im Setup wird der Befehl als `mago format` verwendet, während die Werkzeugbeschreibung auch `mago fmt` nennt.

Der Architekturwächter besteht aus zwei Teilen. Der Perimeter Guard begrenzt Abhängigkeiten zwischen Schichten. Der Structural Guard legt Bedingungen für Klassen und Symbole fest, etwa finale Controller mit einem bestimmten Namensmuster. Damit deckt Mago Einsatzfälle ab, die auch mit Deptrac und PHPArkitect verbunden sind.

Der Befehl `mago cst` zeigt den Concrete Syntax Tree und dient der Fehlersuche im Parser sowie der Entwicklung eigener Regeln. Dokumentiert sind `mago cst src/Kernel.php`, `mago cst src/Kernel.php --tokens`, `mago cst src/Kernel.php --json` und `mago cst src/Kernel.php --names`.

Nach dem eigenen Benchmark des Projekts lintet Mago eine Codebasis ungefähr 29-mal schneller als PHP-CS-Fixer. Rust erzeugt nativen Code. Die Pipeline verteilt ihre Arbeit auf die verfügbaren CPU-Kerne.

Die Installation ist über den Shell-Installer oder Composer möglich. `mago init` liest die PHP-Version und die Quellverzeichnisse aus `composer.json` und erzeugt danach `mago.toml`. Der zentrale Ablauf verwendet `mago format`, `mago lint`, `mago analyze` und `mago guard`. `mago config` zeigt die aktive Konfiguration. `mago list-files` listet die analysierten Dateien.

Mago verwendet standardmäßig TOML. YAML und JSON werden ebenfalls unterstützt. Eine minimale Datei kann `version = "1"`, `php-version = "8.3"` und unter `[source]` den Eintrag `paths = ["src", "tests"]` enthalten. TOML arbeitet mit UTF-8 und unterscheidet Groß- und Kleinschreibung. Tabellen beginnen mit Headern, Tabellenarrays mit doppelten eckigen Klammern.

Globale Schlüssel müssen vor dem ersten Tabellen-Header stehen. Backslashes in PHP-Namespaces brauchen in doppelt quotierten Strings eine Verdopplung. Doppelte Schlüssel oder Tabellen sind ungültig. `php-version` muss als String quotiert werden, weil `8.3` sonst als Zahl gelesen wird. VS Code mit Even Better TOML kann die Datei prüfen.

Zu den globalen Optionen gehören `threads`, `extends`, Includes für Quellen und Ausschlüsse. Der Formatter bietet unter anderem `print-width`, `use-tabs`, `tab-width`, `single-quote`, `trailing-comma` und Ausschlussregeln. Für CI steht `mago format --check` zur Verfügung.

Der Linter unterstützt Framework-Integrationen, Baselines, `minimum-fail-level` und Regeln mit eigenen Einstellungen. Als Beispiele nennt der Artikel Symfony- und PHPUnit-Integrationen, `no-else-clause` mit der Stufe warning sowie `cyclomatic-complexity` mit einem einstellbaren Schwellenwert. `mago lint --explain <rule>` erklärt einzelne Regeln. Der Analysator kann Prüfungen ignorieren, Baselines und Plugins verwenden sowie zusätzliche Strenge schrittweise aktivieren.

Guard-Regeln werden mit TOML-Tabellen und Tabellenarrays beschrieben. Ein Perimeter kann Schichten wie `App\\Domain`, `App\\Application` und `App\\Infrastructure` definieren und Berechtigungen wie `@self` und `@native` vergeben. Strukturregeln können auf `App\\Controller\\**` zielen und eine finale Klasse mit dem Namen `*Controller` verlangen. Weitere Regeln lassen sich für Namespaces und Symbole anlegen.

Mago kann Aufgaben mehrerer etablierter PHP-Werkzeuge abdecken. Die vorhandenen Plugin-Ökosysteme und Framework-Erweiterungen der älteren Projekte werden jedoch noch nicht vollständig erreicht. Der Artikel empfiehlt deshalb, Mago zunächst parallel einzusetzen, die Ergebnisse zu vergleichen und einzelne Werkzeuge erst nach einer Prüfung der Projektabdeckung zu entfernen.