Thank you in advance for opening an issue for the panic—that's super helpful.
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:
That's a great point, and you've touched on what might seem like a paradox: while the toolset is ambitious, keeping up with new PHP features is actually one of Mago's biggest strengths.
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.
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.
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:
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!