When I announced Mago 1.0.0-rc.1, I promised it would include a Language Server Protocol (LSP) implementation. Today, I'm making a difficult but necessary decision: the LSP will be delayed to version 2.0.0.
This article explains the technical and strategic reasons behind this decision, what it means for Mago's future, and how I plan to deliver an LSP that meets the standards the community deserves.
What I Could Ship Today
If I shipped an LSP with Mago 1.0.0-rc.1, it would provide:
- Diagnostic reporting for linter, guard, and analyzer
- File formatting
That's it. Two features. While these features are useful, they fundamentally miss the point of what a Language Server Protocol implementation should be.
The Real Question: What Makes an LSP Worth Installing?
Ask yourself: why do developers install LSP extensions in Neovim, Zed, VS Code, or any other editor? Is it just for error reporting and formatting?
No. Developers want a complete development environment for PHP that provides:
- Renaming – refactor symbol names across the codebase
- Go to definition – jump to where a class, function, or constant is defined
- Find references – see everywhere a symbol is used
- Autocomplete – intelligent code completion with type information
- Hover information – view documentation and type signatures
- Auto-import – automatically add use statements
- Code actions – quick fixes and refactorings
- Fault-tolerant parsing – work seamlessly even with incomplete or invalid code
These features are the fundamentals that any serious LSP must provide. An LSP that only reports errors lacks the features developers actually need in their daily workflow.
Why I'm Building My Own LSP
The PHP ecosystem already has several LSP implementations. So why create another one? Because existing solutions have significant limitations:
- They're slow – performance degrades on large codebases
- They're paid – require expensive licenses for teams
- They're closed source – can't be audited, fixed, or extended by the community
I want to build something different: a fast, free, and open-source LSP that performs well on codebases of any size. I refuse to compromise on quality to hit an arbitrary deadline.
Technical Challenges I Need to Solve
Building a production-ready LSP requires fundamental changes to Mago's architecture, not just implementing features:
1. Parser Fault Tolerance
The current parser, while capable, accepts semantically invalid code like:
declare(strict_types=10) // invalid value
function foo(never $x) {} // invalid parameter type
enum Foo: Foo {} // non-`int`/`string` backing type
An LSP needs to handle much more:
- Partial, incomplete code as users type
- Missing semicolons
- Unclosed braces, brackets, or parentheses
- Half-written expressions and statements
- Files with multiple syntax errors
The parser needs to recover gracefully from errors and produce a meaningful Abstract Syntax Tree (AST) even when code is incomplete. This is a significant engineering effort.
2. Orchestrator Redesign
The current orchestrator needs major architectural changes to support:
- Virtual filesystems – handle unsaved editor buffers
- Incremental parsing – reparse only changed portions of files
- Concurrent analysis – handle multiple concurrent requests efficiently
- Workspace management – track dependencies across projects
- Memory efficiency – maintain performance with editor open for hours
These changes represent a fundamental redesign of how Mago processes PHP code.
3. Feature Implementation
Each LSP feature requires careful design and implementation:
- Renaming needs symbol resolution across the entire codebase, understanding scope, and safely updating all references
- Go to definition requires accurate position tracking, jump-to-definition across files, and handling of inherited members
- Autocomplete needs context-aware suggestions, type inference, and ranking of results
- Find references requires indexing all symbol usage and incremental updates
- Hover information needs documentation extraction and type signature formatting
Each of these features is a project in itself.
My Strategy: Quality Over Speed
I face a choice between two options:
Option A: Ship a minimal LSP now, disappointing users who expect more
Option B: Delay the LSP, deliver quality CLI tools now, and build toward a complete LSP
I've chosen Option B.
Mago 1.0.0: Production-Ready CLI Tools
Mago is already being used in production by major companies. The 1.0.0 release will focus on what Mago does exceptionally well:
- Static analysis – find bugs before they reach production
- Code formatting – consistent style across teams
- Linting – enforce code quality standards
- Architectural enforcement – maintain project structure with guards
- Performance – blazing fast analysis of large codebases
These tools are mature, tested, and ready for widespread adoption.
Watch Mode: A Glimpse of LSP-Like Responsiveness
As part of the 1.0.0-rc.1 release, I'm introducing a new --watch flag for the mago analyze command. This feature watches your project for changes and automatically re-analyzes, providing much faster feedback during development.
The architecture behind watch mode was originally built for the LSP. Since the full LSP won't be ready for 1.0.0, I decided to expose this capability through the CLI. This means incremental analysis is already working internally. You'll get a taste of LSP-like responsiveness without needing editor integration.
The 1.x Series: Building Blocks
During the 1.x release cycle, I'll introduce LSP building blocks incrementally:
- Improved fault-tolerant parser
- Go-to-definition capabilities
- Reference finding
- Autocomplete engine
- Virtual filesystem support
Each of these will be available as CLI tools or library components, allowing the community to benefit from them immediately while I integrate them into a cohesive LSP.
Mago 2.0.0: The Complete LSP
The 2.0.0 release will deliver the full LSP implementation with all essential features working seamlessly together. It will be fast, comprehensive, and free.
Why Not Wait for LSP Before Releasing 1.0.0?
If I committed to including the LSP in 1.0.0, I'd be looking at 6 to 12 months of additional development time. This would mean:
- Companies and developers who need Mago's CLI tools today would have to keep using pre-release versions
- Bug fixes and improvements would be tied to an arbitrary LSP deadline
- The PHP community would miss out on a stable, production-ready static analysis tool
Mago already solves real problems for real teams. Holding back the stable release just for the LSP doesn't serve anyone.
The Reality of Open Source Development
I made a promise about the LSP timeline, and I'm breaking it. I need to be honest about why.
Mago is an open-source, free project, sponsored by the PHP community. While I'm incredibly grateful for the support I've received, sponsorship doesn't cover the cost of full-time development. Building a production-grade LSP is a massive undertaking that requires sustained, focused effort. That's effort I can only give in the evenings and weekends around my day job.
How You Can Help
If you want to see Mago's LSP become a reality faster, you can support ongoing development through GitHub Sponsors: @azjezz
Every contribution helps me dedicate more time to Mago's development.
My Commitment to the Community
I understand that delaying the LSP is disappointing. I share that disappointment. I want to see Mago's LSP in action as much as you do.
Quality matters more than timelines. The PHP ecosystem deserves an LSP that's fast, feature-complete, and reliable. I'm committed to delivering exactly that, even if it takes longer than I initially hoped.
Mago 1.0.0 will be an excellent release, providing production-ready tools that improve PHP development today. The LSP will come in 2.0.0, and it will be worth the wait.
Thank you for your understanding and continued support.
Follow Mago's development:
- GitHub: github.com/carthage-software/mago
- Documentation: mago.carthage.software