Mago 1.9.1

Patch release with several analyzer and formatter bug fixes, plus support for @psalm-mutation-free annotations.

✨ Features

Codex (Type System)

• @psalm-mutation-free and @psalm-external-mutation-free annotations: The codex scanner now recognizes these Psalm annotations and maps them to Mago's internal mutation-free flags, improving interoperability with Psalm-annotated codebases (#1157)

🐛 Bug Fixes

Analyzer

• Property narrowings preserved across pure and mutation-free function calls: Previously, all property type narrowings were cleared after any function call that received an object argument. The analyzer now preserves property narrowings when the called function is marked as @pure, @mutation-free, or @external-mutation-free, since these functions are guaranteed not to mutate the object's state (#1157)
• Generic type parameters preserved during instanceof narrowing on sealed class hierarchies: When narrowing a generic type (e.g., Result<T>) with instanceof against a sealed inheritor (e.g., Success<T>), the type parameters from the parent type are now correctly carried over to the narrowed type, preventing unexpected never type results (#1156)
• Non-existent classes detected in @var annotations and instanceof RHS: The analyzer now reports non-existent-class-like errors for undefined types used in @var docblock annotations and on the right-hand side of instanceof expressions, matching the existing behavior for parameter types, return types, and property types (#1007)
• Possibly undefined keys in unions of sealed/unsealed arrays: Fixed incorrect undefined-string-array-index errors when accessing keys on union types containing both sealed and unsealed array variants (e.g., array{foo: int, ...}|array{foo: int}). The unsealed variant's generic parameters are now properly considered when determining whether a key might exist (#1154)
• Deduplicated undefined key errors across union variants: When accessing a non-existent key on a union of multiple keyed arrays, the undefined-string-array-index error is now reported only once instead of once per union variant

Formatter

• Trailing comments preserved on opening parenthesis line in multiline parameter lists: Fixed a bug where end-of-line inline comments (e.g., // @phpstan-ignore method.unused) on method signatures with multiline parameter lists were incorrectly moved to the next line (#1153)

Prelude (Type Stubs)

• DateTimeImmutable and DateTimeZone methods annotated as mutation-free: Methods on DateTimeImmutable and DateTimeZone that do not modify state are now annotated with @mutation-free, preventing false positive property narrowing invalidations when calling these methods (#1157)
• ReflectionClass::getReflectionConstants() return type: Added missing return type information (#1152)

Documentation

• Removed undocumented space_after_colon_in_enum_backing_type setting: Removed a reference to a non-existent formatter setting from the configuration reference documentation (#1151)

🙏 Thank You

Contributors

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

• @BafS — #1152
• @dotdash — #1154
• @ptondereau — #1151

Issue Reporters

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

• @Bleksak — #1007
• @MartkCz — #1153
• @Nadyita — #1157
• @wryk — #1156

Full Changelog: 1.9.0...1.9.1