Are extensions/plugins possible and feasible?

[oprypkhantc]

Hey again.

Another question is about extensions. Currently, there are built-in integrations that are shipped with Mago, for some of the frameworks and libraries.

Some of these integrations, like Laravel's, don't provide basically any of the features that a typical Laravel codebase would need. In PHPStan world, there's a quite big extension - Larastan, which handles Laravel integration with PHPStan.

There's a lot of weird magic that Laravel does. Unfortunately, in a lot of cases Larastan must boot your application in order to get information that's not accessible statically just from looking at the code. In other cases, Larastan relies on defining stub files to overwrite incorrect types in the Laravel framework itself (common occurrence unfortunately).

The question is - is it possible to implement an extension to Mago without a fork? How feasible would it be to keep a bootstrapped PHP application running in the background, and the Mago extension to talk to it for information? Are there any hooks in the Analyser that could be used to do so? Is it possible to use PHP stub files to overwrite definitions from the original source?

[azjezz]

Hi! That's a great question. Extensibility is a long-term goal, and our approach differs between the analyzer (which needs deep, type-aware plugins) and the linter (which uses simpler, syntax-based rules).

Here’s a summary of the plan:

Analyzer Plugins (Future)

A public plugin system is planned, which will most likely be built using wasm (WebAssembly).

• How it would work: You would write a plugin in a separate Rust project, compile it to a .wasm file, and load it via your mago.toml configuration. This means no fork of Mago would be required.
• Current Status: This is a long-term goal. Our current priority is to ensure the core analyzer is rock-solid with standard PHP features. We do have a limited internal system for providing custom type information for specific functions as a proof of concept ( ref https://github.com/carthage-software/mago/tree/main/crates/analyzer/src/invocation/special_function_like_handler ).
• Limitations: The initial plugin system will focus on static analysis hooks. Runtime analysis (like communicating with a bootstrapped PHP application) is a much harder problem and is not part of the initial plan.

Stub Support (Available Now)

You can override definitions from vendor packages or even PHP's built-in symbols today. Mago loads symbols with a clear priority order:

1. paths (Your project's source code) - Highest priority
2. includes (Stubs, vendor code) - Medium priority
3. Built-in PHP Symbols - Lowest priority

How to Override Symbols

• To Override Vendor Code: Add your stub directory to includes and add the original vendor file you want to replace to excludes.
• To Override Built-in PHP Symbols: Simply add your stub file to a directory listed in includes. No excludes are needed because includes has a higher priority than built-ins.

Note: It is best to place stubs in includes, not paths, because files in paths are actively analyzed for errors, while includes are only scanned for definitions.

Linter Custom Rules (Future)

For the linter, we plan to support custom rules written directly in PHP. For widely-used or performance-critical rules, we recommend opening an issue on GitHub to have them built directly into Mago.

[oprypkhantc]

Awesome. Thank you.

Regarding runtime analysis - I believe it would be possible to implement most of Larastan in such a way that it's bootstrapped and killed immediately, spitting out all of the necessary information ahead of time. Of course, it would still necessitate having a hook where that could be done, and it wouldn't work correctly with the LSP, as tracking changes would be a nightmare. But at least it would be something for Laravel applications.

[azjezz]

That's a really interesting approach, and it actually aligns with a potential solution we've considered.

We could technically provide an API for plugins to execute an external command. A plugin could launch a PHP script that bootstraps the application, gathers all the necessary information, and then spits it out as JSON to standard output for Mago to consume.

This also solves the LSP problem you mentioned. A plugin could re-run this command to "refresh" its data whenever needed. The refresh could be triggered intelligently, for example, whenever a specific file (like a service provider) or a directory changes, or even manually by the user.

So, while it's not on the immediate roadmap, it's definitely a feasible path for deep framework integration in the future.