Mago 1.11.0

This release adds a --staged flag for seamless pre-commit hook integration, a new imprecise-type analyzer diagnostic for bare array/iterable type hints, support for class-like constants in array shape keys, and several bug fixes across the analyzer, formatter, and Composer installer.

✨ Features

CLI

• --staged flag for lint and analyze: New --staged flag restricts linting and analysis to files currently staged in Git, making pre-commit hook setup straightforward. When combined with --fix, changed files are automatically re-staged so that fixes are included in the commit (#1199)

Analyzer

• imprecise-type diagnostic for bare array/iterable type hints: The analyzer now warns when parameters, returns, or properties use bare array or iterable type hints without a corresponding docblock annotation specifying the element types. This encourages more precise type documentation across your codebase (#1191)

Type System

• Class-like constants as array shape keys: PHPDoc array shapes now support class constants as keys (e.g., array{MyClass::FOO: string, MyEnum::Bar: int}), enabling more precise type definitions for constant-keyed arrays (#1190)

🐛 Bug Fixes

Codex

• Type aliases in class-string<T> generics: Fixed a bug where type aliases (e.g., @psalm-type, @phpstan-type) used as the generic parameter in class-string<T> annotations were not resolved, causing false positives (#1202)
• @inheritDoc across intermediate classes: Fixed false incompatible-parameter-type positives when a child class inherited docblock types from a grandparent through an intermediate class that didn't redeclare the method (#1189)

Analyzer

• Improved #[Override] error for trait methods: When #[Override] is used on a trait method that doesn't override any parent, the diagnostic now suggests adding a @require-implements annotation to the trait if the method is intended to override an interface method (#1192)

Formatter

• Parentheses around elvis/ternary in property access chains: The formatter no longer strips necessary parentheses from expressions like ($a ?: $b)->method() or ($a ? $b : $c)->prop, which would change the runtime semantics (#1198)

Prelude (Type Stubs)

• Incorrect @pure annotations removed: Removed incorrect @pure annotations from debug_zval_dump(), error_log(), phpinfo(), and php_sapi_name() which could mask side-effect analysis (#1195)
• Multiple stub corrections: Fixed several incorrect type stubs affecting analysis accuracy

Composer

• Windows binary download fixed: The Composer installer now correctly downloads .zip archives for Windows MSVC targets instead of requesting non-existent .tar.gz files, which caused 404 errors when invoking vendor/bin/mago (#1196)
• Installer refactored with proper architecture support: The installer script has been reorganized into composable, documented functions under the Mago\Internal namespace. Unsupported architecture targets have been removed and ARM v5/v6 detection has been added, with clear error messages when a platform has no pre-built binary

📖 Documentation

• Reserved MAGO_ environment variable prefix: Documented that all environment variables starting with MAGO_ are reserved for configuration. Unrecognized MAGO_-prefixed variables (e.g., from CI tools) cause configuration errors. The docs now explain how to diagnose and resolve this (#844)
• Dynamic benchmarks page: The benchmarks documentation page now fetches live data from the PHP toolchain benchmarks dashboard instead of using hardcoded numbers, keeping performance comparisons up to date
• Pre-commit hook recipes: Updated documentation with examples for using --staged with --fix to automatically fix and re-stage files in pre-commit hooks

🙏 Thank You

Contributors

A huge thank you to everyone who contributed code to this release:

• @dotdash — #1197
• @kzmshx — #1189, #1195

Issue Reporters

Thank you to everyone who reported issues and requested features that shaped this release:

• @dragosprotung — #1192
• @edsrzf — #1199, #1200
• @karoun — #1190, #1191, #1202
• @Magiczne — #844
• @marcovmun — #1198
• @Taelkir — #1196

Full Changelog: 1.10.0...1.11.0