Mago: A fast PHP toolchain written in Rust
github.com
github.com
I've just tried to apply it to a medium-sized project, and it spitted tens of thousands of errors where phpstan and psalm don't see any. At first glance, it's because Mago does not parse phpdoc. In its current beta state, Mago is meaningless for all the big PHP projects, which are its main target.
Mago might succeed, but I wouldn't bet on it. Its main selling point is that it promises to be faster than the usual static analysers-linters (phpstan and psalm). But if it does not reach feature parity with them, the speed gain probably won't convince PHP projects to drop the standard tools. Since phpstan and Co keep evolving, keeping feature parity will require constant work. And PHP is more niche than Python or JS, so contributors mastering Rust and PHP will be fewer, compared to phpstan/psalm which are written in PHP.
The online playground is running a very old version (~0.20.0 from months ago, which did not even have a static analyzer) and gives a poor impression of the current tool. That's on me to fix or take down.
The issue you saw with built-in classes like `RuntimeException` was absolutely a bug in those early alpha versions, but it has been fixed for a long time now. The analyzer has matured a lot since then.
The current beta is stable enough to be the sole static analysis tool for a couple of extremely well-typed projects:
- https://github.com/azjezz/psl/ - https://github.com/carthage-software/cel-php
I'd definitely encourage trying the latest release locally to get a real feel for it. Thanks again for the write-up!
You're right that the README should be clearer about the beta status and the current feature set. That's a great suggestion, and I'll get that updated.
Regarding the errors you saw, I suspect the main culprit isn't a general lack of PHPDoc parsing, but rather the two biggest remaining features we're actively working on: support for magic _@method_ and _@property_ tags. Mago has full support for generics (@template), assertions (@psalm-assert*), conditional types, etc., but the absence of those two is definitely a major source of noise on established projects right now. They are our top priority and should land in the next beta release.
On the topic of feature parity, you're right that it's a moving target. Our goal isn't to be a 1-to-1 clone of Psalm or PHPStan, but a different tool with its own strengths (see: https://github.com/carthage-software/mago/discussions/379). For example, Mago will flag code like `[0 => $a, $b] = ["a", "b"]` as an error, which other tools currently do not.
We're very aware of the current noise level. We test Mago daily against massive, multi-million-line codebases. On one such project, the first beta reported ~250,000 errors; we're now down to ~30,000. While still a lot, it shows how quickly we're closing the gap on false positives.
Thanks again for the valuable feedback. It's a long road, but we're confident we can reach and surpass the current standards in a very short time.
I suggest that stating them prominently would help the project. When I read Mago's home page, I downloaded the latest release, followed the "Getting started" process on a local repository, then nearly lost interest when I saw the amount of false errors. If I had first read "here is our goal, with this roadmap, this kind of validation on real projects, and this position toward existing well-known tools", I would have been much more willing to follow the project and accept its false positives.
As a side note, for my first try with Mago, I think its lack of parsing `@property` was a major source of false errors, because the source code it analyzed had a few omnipresent classes that used it. BTW, Mago panicked when I tried to lint another repository... I'll open a issue.
You are 100% right about the documentation and managing expectations on the home page. That's a failure on my part, and based on your feedback, I'll make it a priority to be much clearer about the project's beta status, goals, and roadmap.
The lack of @property and @method support was the single biggest source of noise on established codebases. The good news is that this is exactly what we've been focused on, and support for both was just merged in the past few hours:
@method support is now quite robust: - https://github.com/carthage-software/mago/commit/c76795c30de... - https://github.com/carthage-software/mago/commit/dc333edb261...
@property support is about 95% there, and we're ironing out the last few edge cases as we speak: - https://github.com/carthage-software/mago/commit/9e8d30b0672... - https://github.com/carthage-software/mago/commit/0330791a9d3...
Hopefully, the next release will provide a much better experience out of the box. Thanks again for taking the time to write this up!
Will Mago implement a PHP runtime?
Absolutely not. The PHP runtime is incredibly complex. Major efforts by large companies (e.g., Facebook's HHVM, VK's KPHP) have struggled to reach full parity with Zend Engine. Achieving this as a smaller project is infeasible and would lead to community fragmentation. We are focused on tooling, not runtimes.
Say this to the team behind Ladybird browser: https://awesomekling.substack.com/p/how-were-building-a-brow...
(Items 5 and 3 on the list in the linked page.)
A transpiler might read PHP and spit out C, or Java or some other existing programming language, spitting out the code for a virtual machine doesn't make you a transpiler unless you're going to argue that all compilers are just transpilers, it's like one of those "Actually goats are fish" arguments. OK, but now the word "fish" is useless so why go to this bother ?
It's a small thing in the Rust community but it's pretty huge in the world simply because there are so many Python developers (and also because of the extreme magnitude of improvement). Probably wouldn't have happened without Rust.
Ripgrep, fd, tokei, Just, zellij, uv, and so forth. Porting languages has given the opportunity to remove some of the cruft decided on a whim in the 70s. None of these are world changing, but they do make life easier than the originals.
I wonder why, too. Now, you can give me a reply for why you think that is, which you could have done without this comment, or you can just keep adding noise to this thread. Up to you.
Rust (or Go) are about the only popular languages around that can meet the spec. That Rust will always be theoretically more performant than GC Go makes it the more attractive option for re-imagining some of these bedrock utilities.
Granted, not all of them are popular, but that is how Rust started off, too, right?
---
Ada would have been great as it is quite mature and used for serious and critical software, but lacks the "cool factor" that Rust has.
I would like to add, that there is clearly a disconnect between technical merit and adoption. Ada is a perfect example of this. It has been around since the 1980s with:
* Stronger safety guarantees than Rust in many ways (stricter type system, built-in contracts, formal verification support)
* Proven track record in safety-critical systems (aerospace, defense, medical devices)
* Native compilation with no runtime overhead
* Mature toolchain and decades of real-world deployment
* ... and much more.
If safety was truly the driving factor, Ada should have dominated systems programming decades ago. But it didn't, and that reveals what's really going on.
I believe that Rust was chosen over Ada because of:
* Timing - arrived when web developers were ready to try systems programming
* Community building - excellent documentation, welcoming culture, modern package manager[1]
* Aesthetic appeal - syntax familiar to C/Java/JavaScript developers
* Marketing narrative - "systems programming without fear", i.e. fuckton of hype
Ada had superior safety for decades but lacked the cultural momentum. It was associated with DoD contracts and enterprise software, not cool indie CLI tools.
[1] Ada has Alire now as its modern package manager.
Whereas anyone who uses Python would have heard of uv and why it’s much faster than other tools.
But even if you're not wrong, a major mission of Rust was to be a safer C/C++, and language tooling used to be dominated by those languages.
1. Banning shared, mutable data. You can't change data that other code might be reading. This is a huge win for threading and multiple CPUs, but it's a dramatic departure from other popular languages.
2. Knowing how data is laid out in memory. This is classic "systems programming" stuff, and it's also present in C, C++, Zed, etc. This usually goes along with making memory allocation visible (though not always in C++). This is a big win for performance.
If you wanted to build a "scripting language" version of Rust, you could probably lose (2). Languages like Haskell are even stricter than Rust, but they hide the details of memory layout. But then you need to decide whether to keep or lose (1). If you keep it, your language will have good threading, but users will need to think about ownership and borrowing. If you lose (1), then your language won't feel very much like Rust.
It would be an interesting intellectual exercise! But actually turning it into a popular scripting language would probably require the same luck and the same 10 years of work that most successful languages need to get real traction.
Not really no. I work on an interpreted language runtime in Rust professionally and it's still a huge help even if you're still eating perf pain on the interpreted language itself for the same reasons everyone else does. There's more benefit to Rust than you're really capturing here but that's to be expected, it's a short comment.
Here are some other things we get from using Rust for interpreted languages:
- The `unsafe` parts are relatively limited in scope and we have much better and more automated verification tools for `unsafe`, especially WRT undefined behavior
- Being able to make large architectural changes and work through them mechanically/quickly because of the type-checking and borrow-checking is absurdly powerful for any project, all the more so in this context.
- The library ecosystem for Rust has been fantastic for all kinds of projects but it's especially good for PL runtimes.
- LLMs are a lot better at Rust than other programming languages. I have a lot of experience using LLMs in a variety of domains and programming languages and it's far better at Rust than anything else that's expressly about programming. Arguably it's even better at Terraform and Ansible but I consider that a different category. Controversial point maybe but I get tremendous yield out of it.
- It's not just that Rust is fast. It is on par w/ C/C++ all else being equal. What's significant here is that it is a _lot_ quicker/easier to hit the 80/20 perf targets as well as the bleeding edge performance frontier in a Rust application than it is in C and C++. A lot of C and C++ projects leave performance on the table either because it's too hard to make the ownership model human-maintainable/correct or because it would be too much work to refactor for the hoped-for perf yield. Not as much an issue in Rust. You can gin up hypothetical perf improvements in Rust with gpt-5 lickety-split and the types/borrowck will catch most problems while the agent is iterating.
Shared, mutable data aren't really banned, we use it strategically in our Rust interpreter, it's just not default-permitted. Aliasing is precisely the distinction between a safe reference and an unsafe pointer in Rust. Aliasing a mutable pointer in Rust isn't UB, it's just `unsafe`. OTOH, aliasing a mutable reference _is_ UB and not allowed in Rust. Miri will catch you if you do this.
On top of all that, you have some nice kit for experimenting with JIT like Cranelift.
I am a huge Rust fan, but never really got a chance to write it in the modern LLM era. It makes absolute sense that the borrow checker would make LLM agent-driven refactors easier.
Thanks for giving Raku a test drive (https://raku.org)
While Raku can access all the perl CPAN modules and Python modules via Inline::Perl5 and Inline::Python, I agree native modules are also a good indication of the level of "adoptability" of a language.
I would say that Raku is currently ready for "bleeding edge" and "early-adopters" but not for "early-main" (terms from Crossing the Chasm)
For example, there are three pretty nice actively maintained web framework libraries:
- Cro (also HARC stack that uses Cro)
- Hummingbird
- Web::App
Similar stories for each of the domains you mention: https://chatgpt.com/share/68c67f75-d654-8009-9c8d-fdb1081869...
What do you need a scripting language for that's different than using Rust?
Cargo only recompiles the crates that you edit, after the first build of the dependent crates it's quick to iterate.
Compilation is not the bottleneck, it's the human (me) in the loop that's doing the thinking and typing.
The productivity boost comes from Rust's strong type system and ownership (much better than MyPy) which practically ensures that if it compiles, it will work. There's a lot less troubleshooting/debugging of my Rust "scripts" than when I wrote Python.
If it has remotely the same success, that would be a huge win for the ecosystem!
With Phpstan and Psalm already in the space I'd like to see more differentiator features than 'written in Rust' - there are certainly advantages to that, but the disadvantage of not using PHP is it's harder to get contributions from the community using the tool.
Cool project overall!
Tools like Sorbet (C typechecker for Ruby) or tsgo (Go-based successor to TypeScript's typechecker) are only viable because big profitable companies can back them up with engineering hours.
FrankenPHP has >100 contributors, including 3 very frequent ones, and about 17k lines of Go.
Mago has 11 contributors, with just 1 very frequent one, and about 135k lines of Rust.
Why do you think so?
The PHP Foundation has raised over 2 million USD in contribution and has over 500K in their balance currently according to:
https://opencollective.com/phpfoundation
PHP has some well funded groups using it like Wordpress, Wikipedia, Laravel to name a few.
And recently the PHP Foundation started officially sponsoring a Go project, FrankenPHP.
https://thephp.foundation/blog/2025/05/15/frankenphp/
So PHP looks like a friendly and well supported community to foster tooling made in other languages.
This is great, but it is still dwarfed by the amount Microsoft has spent on TypeScript and also by the amount Stripe has spent on Sorbet.
500k is roughly comparable to the amount my previous company spent (grudgingly) to keep me employed and working on PHP tooling for a couple of years.
TypeScript is a very complex language with a huge mission. From the same creator of C#.
Sorbet is trying to tame a dynamically typed language which supports monkey patching. Stripe can get away with it because they have close to infinite money and a large Ruby codebase.
Meanwhile PHP is stable and typed. Parsing AST, linting and formatting are trivial in comparison to the examples you cited. Their package manager, composer, is also boring a stable, in a good way. Prime target for a second pass if need be.
Why do you feel the need to personally discredit me instead of sticking to constructive arguments?
And where did I say Mago wasn't a static analysis tool?
I'm glad you wrote Psalm. However I and most of the PHP community use https://phpstan.org instead, as you may know.
At the time I made this choice on technical grounds. Then PHPStan found a way to stay profitable with PHPStan Pro while Psalm stagnated, which cemented my decision. Recently, vimeo being acquired by Bending Spoons doesn't help either since psalm still lives in https://github.com/vimeo/psalm
The big challenge to typechecking PHP is that it’s essentially two different languages — there’s typechecking code like Laravel that makes heavy use of magic methods (effectively impossible statically) and typechecking code that doesn’t (very doable).
Psalm was mostly designed for the latter, whereas PHPStan excelled at the former with dynamic analysis in plugins like Larastan.
That dynamic analysis — where you have to run some PHP code to make sense of a PHP codebase — is another big reason a Rust-based tool will have a hard time becoming popular in the PHP ecosystem.
And yeah, the parts which I don't like about Laravel are usually related to magic. IDEs often need extensions to understand Laravel which imo is not a good look.
Composer is one of the best package managers in any language ecosystem but beyond that, other PHP tooling, while technically well maintained, aren't particularly great at what they do. It's an ideal starting point for positive disruption.
Composer is a good tool, but it's resource usage was abysmal.
The traditional PHP tooling ecosystem relies on a dependency chain. A new syntax feature has to be implemented in a core library like nikic/PHP-Parser, then released, then adopted by tools like Psalm or PHPStan, and then finally those tools make a new release. This process can take weeks or months.
Because Mago is a single, cohesive toolchain, we control the entire stack. We can add support for new syntax across the lexer, parser, formatter, linter, and analyzer in one go.
For example:
- Mago's formatter and analyzer already have full support for the Pipe Operator (`|>`) and `clone with` from the upcoming PHP 8.5. The pipe operator was implemented across the entire toolchain in about 30 minutes, just hours after its RFC was approved. - For comparison, many existing tools are still catching up with PHP 8.4 features like Property Hooks.
This agility is a core part of the project's value proposition.