Mago es un binario estático para la calidad del código PHP, desarrollado en Rust. Reúne el formateo, el linting, el análisis estático y el control arquitectónico con un parser y una configuración compartidos.

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

El proyecto publica versiones estables 1.x desde diciembre de 2025. La versión 1.51.2 era la disponible cuando se escribió el artículo. Mago es software libre y de código abierto bajo las licencias MIT o Apache 2.0.

Un proyecto PHP habitual combina PHP-CS-Fixer o PHP_CodeSniffer para el estilo, PHPStan o Psalm para el análisis y herramientas como Deptrac para las dependencias. Cada paquete suele tener su propia configuración y su propio proceso. El binario estático de Mago no necesita un runtime de PHP para ejecutar estas comprobaciones.

El analizador se ejecuta con `mago analyze`. Detecta errores de tipos, código sin uso y condiciones imposibles. Admite anotaciones de PHPStan y Psalm, genéricos, tipos condicionales y flow narrowing.

`mago lint` comprueba la corrección, la coherencia y la seguridad. La versión 1.51.2 ofrece 190 reglas en nueve categorías. Muchas incidencias pueden corregirse automáticamente. El formateador produce resultados deterministas y sigue PER-CS por defecto. También incluye presets para psr-12, laravel y drupal. La sección de instalación utiliza `mago format`, mientras que la descripción de la herramienta también menciona `mago fmt`.

El control arquitectónico tiene dos partes. El perimeter guard limita las dependencias entre capas. El structural guard impone condiciones sobre clases y símbolos, como exigir que los controladores sean finales y sigan una convención de nombres. Estas funciones cubren casos relacionados con Deptrac y PHPArkitect.

El comando `mago cst` permite inspeccionar el Concrete Syntax Tree para depurar el parser y desarrollar reglas propias. Las formas documentadas son `mago cst src/Kernel.php`, `mago cst src/Kernel.php --tokens`, `mago cst src/Kernel.php --json` y `mago cst src/Kernel.php --names`.

Según el benchmark publicado por el proyecto, Mago hace lint sobre una base de código aproximadamente 29 veces más rápido que PHP-CS-Fixer. Rust genera código nativo. El pipeline trabaja en paralelo con los núcleos de CPU disponibles.

La instalación se puede hacer mediante el instalador de shell del proyecto o Composer. `mago init` detecta la versión de PHP y los directorios de código desde `composer.json`, y después crea `mago.toml`. El flujo principal utiliza `mago format`, `mago lint`, `mago analyze` y `mago guard`. `mago config` muestra la configuración efectiva. `mago list-files` indica qué archivos se analizarán.

Mago usa TOML por defecto, aunque también admite YAML y JSON. Una configuración mínima puede definir `version = "1"`, `php-version = "8.3"` y, dentro de `[source]`, `paths = ["src", "tests"]`. TOML utiliza UTF-8 y distingue mayúsculas y minúsculas. Las tablas comienzan con una cabecera y los arrays de tablas con dobles corchetes.

Las claves globales deben aparecer antes de la primera cabecera de tabla. Las barras invertidas de los namespaces de PHP deben escaparse en las cadenas con comillas dobles. Las claves y tablas duplicadas producen un error. `php-version` debe escribirse como cadena, porque `8.3` se interpretaría como un número. VS Code con la extensión Even Better TOML puede validar el archivo.

Entre las opciones globales están `threads`, `extends`, las inclusiones de fuentes y las exclusiones. El formateador ofrece `print-width`, `use-tabs`, `tab-width`, `single-quote`, `trailing-comma` y exclusiones. En CI se puede usar `mago format --check`.

El linter admite integraciones de frameworks, baselines, `minimum-fail-level` y ajustes por regla. Los ejemplos incluyen las integraciones de Symfony y PHPUnit, `no-else-clause` con nivel warning y `cyclomatic-complexity` con un umbral configurable. `mago lint --explain <rule>` explica una regla concreta. El analizador permite ignorar comprobaciones, usar baselines y plugins, y activar gradualmente opciones de mayor rigor.

Las reglas de guard se escriben con tablas y arrays de tablas TOML. Un perímetro puede definir las capas `App\\Domain`, `App\\Application` y `App\\Infrastructure`, con permisos como `@self` y `@native`. Una regla estructural puede apuntar a `App\\Controller\\**` y exigir una clase final con el nombre `*Controller`. También se pueden definir reglas para namespaces y símbolos.

Mago cubre responsabilidades que suelen repartirse entre varias herramientas PHP consolidadas. Todavía no iguala todos sus ecosistemas de plugins ni sus extensiones específicas para frameworks. El artículo recomienda ejecutarlo primero junto a las herramientas actuales, comparar los resultados y retirar cada componente después de verificar la cobertura del proyecto.