Mago `1.0.0-beta.1` Release Notes 🎉

Welcome to the first beta release of Mago! This is a massive leap forward from the alpha series, bringing transformative performance improvements, a more robust and opinionated formatter, a smarter linter, brand new documentation, and countless bug fixes.

Mago is now faster, more stable, and easier to use than ever before.

🚀 Highlights

Massive Performance Overhaul: The entire memory management architecture has been rebuilt from the ground up using arena allocation and atomized strings. This has resulted in dramatic speedups across the board, with the linter now running up to 6.3x faster and using 91% fewer CPU cycles on large codebases.
Truly Opinionated Formatting: We've embraced our role as an opinionated formatter by removing nearly 40 granular spacing options. Mago now enforces a single, consistent, and modern code style based on the PER standard, ending style debates and simplifying configuration.
Brand New Documentation: The documentation has been completely rewritten and is now available on a new, beautiful VitePress site. It features auto-generated rule documentation, editor integration recipes, and comprehensive guides for every tool.

🏎️ Performance & Architecture

This release introduces foundational changes that make Mago one of the fastest PHP toolchains available.

Arena Allocation: The parser, linter, and formatter now use a per-thread arena allocator. This strategy drastically reduces pressure on the system's memory allocator, resulting in massive speed gains and a lower memory footprint for most operations.
Atomized Strings: The internal string interning system has been replaced with a high-performance Atom implementation, providing lock-free, thread-safe, and globally unique strings for symbols. This is a key factor in the analyzer's performance improvements.
mago-prelude Crate: PHP's built-in function and class stubs are now pre-compiled into a new mago-prelude crate. This enables full stub support in the Playground (WASM) for the first time and speeds up initialization.
Optimized Type System: The core TUnion type in the analyzer now uses Cow (Clone-on-Write) to eliminate millions of heap allocations for common types like int and string, further reducing memory usage and CPU cycles.

✨ Formatter

The formatter has received significant updates focused on stability, correctness, and a stronger, more consistent style.

PER Standard Alignment: The default style for binary operators now follows the PER Coding Style, placing operators at the beginning of a new line in multi-line expressions.
Opinionated Refactor: Nearly 40 granular spacing options have been removed. The formatter now enforces a single, sensible default style, simplifying configuration and guaranteeing consistency.
Idempotence Fixes: Over 20 idempotence bugs have been fixed. Formatting already-formatted code will no longer produce unwanted changes, leading to a much more stable and predictable experience.
New --check Flag: A --check flag has been added to the format command. It exits with a non-zero code if any files need formatting, making it perfect for CI validation.
Bug Fixes: Numerous bugs related to trailing commas, parenthesis handling, and indentation in chained conditions have been resolved.

🕵️‍♂️ Linter

The linter has been completely rewritten from scratch for the beta release. Now a pure, blazing-fast AST-walker, it's smarter, more flexible, and 2-3x faster than the alpha version. Key enhancements include:

New --pedantic Flag: A new --pedantic flag allows you to run every single rule the linter knows about, overriding your configuration and PHP version constraints for the most exhaustive analysis possible.
New Rules: Several new rules have been added, including:
- prefer-first-class-callable: Automatically fixes closures that can be converted to the modern ... syntax.
- use-compound-assignment: Recommends using operators like += and .=.
- no-redundant-nullsafe: Correctly identifies redundant ?-> operators (moved from the analyzer for better accuracy).

🔬 Analyzer

The analyzer now has a clearer separation of concerns and has offloaded some responsibilities to the faster linter.

Linter/Analyzer Separation: Many syntax- and style-related checks have been moved from the analyzer to the much faster AST-based linter. Codebase-aware checks remain in the analyzer.
Bug Fixes: An issue with how the + operator combines arrays has been fixed.

🛠️ CLI & Tooling

The command-line interface and supporting tools have been improved for a better developer experience.

Resilient Baseline: The baseline feature is now much more practical. It no longer uses a file hash or column numbers, meaning you can refactor code or change indentation without invalidating all baseline entries in a file.
Categorized Pragmas: All suppression pragmas (@mago-expect, @mago-ignore) now must be categorized (e.g., @mago-expect analysis:some-issue), making them clearer and more robust.
New code-count Reporter: A new reporting format that groups issues by code and sorts them by frequency, helping you identify the most common problems in your codebase.
Usability Renames: --semantics-only has been renamed to --semantics, and the internal --json-docs flag is now a public --json flag.

📚 Documentation

New Site: The documentation has been completely rebuilt with VitePress and is available at a new URL.
Auto-Generated Rule Docs: The linter rule reference is now generated directly from the source code, ensuring it's always up-to-date.
New Content: New editor integration recipes and improved installation guides have been added.

🚨 Breaking Changes

Configuration Keys are now kebab-case: To improve consistency, all keys in mago.toml must now be in kebab-case. For example, print_width is now print-width.
Pragmas Require a Category: Uncategorized pragmas are no longer supported. You must specify lint: or analysis: (e.g., @mago-expect lint:no-empty).
Removed Formatter Options: Nearly 40 granular spacing options have been removed in favor of a single, opinionated style. Please review your configuration.
Linter/Analyzer Rule Migration: Some rules that were previously configured under the analyzer may now be linter rules.

❤️ Acknowledgements

This beta release would not have been possible without the incredible support from the community. A huge thank you to everyone who has contributed their time and resources. Whether it is a pull request, a detailed issue report, or a $5 donation, your contributions keep the project moving forward and make Mago better for everyone!

A special thanks to:

Need Help Rescuing a PHP Project?

In addition to building Mago, we now offer consulting services. If you need expert help to modernize, refactor, or rescue a complex PHP project, get in touch with us at contact@carthage.software.

carthage-software/mago 1.0.0-beta.1 Mago 1.0.0-beta.1 on GitHub

Mago 1.0.0-beta.1 Release Notes 🎉