Carthage Software

Why Mago 1.0.0 Won't Ship With an LSP

Nov 11, 2025 • par Seifeddine Gmati

When we announced Mago 1.0.0-rc.1, we promised it would include a Language Server Protocol (LSP) implementation. Today, we're 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 we plan to deliver an LSP that meets the standards our community deserves.

What We Could Ship Today

If we shipped an LSP with Mago 1.0.0-rc.1, it would provide:

  1. Diagnostic reporting for linter, guard, and analyzer
  2. 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 We're Building Our 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

We want to build something different: a fast, free, and open-source LSP that performs well on codebases of any size. We refuse to compromise on quality to hit an arbitrary deadline.

Technical Challenges We Need to Solve

Building a production-ready LSP requires fundamental changes to Mago's architecture, not just implementing features:

1. Parser Fault Tolerance

Our 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.

Our Strategy: Quality Over Speed

We 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

We'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, we're 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, we 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, we'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 we 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 we committed to including the LSP in 1.0.0, we'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

We made a promise about the LSP timeline, and we're breaking it. We need to be honest about why.

Mago is an open-source, free project, sponsored by the PHP community. While we're incredibly grateful for the support we'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.

How You Can Help

If you want to see Mago's LSP become a reality faster, there are two ways you can help:

1. Sponsor Development

Support ongoing development through GitHub Sponsors: @azjezz

Every contribution helps us dedicate more time to Mago's development.

2. Hire Carthage Software

We're a consultancy company specializing in PHP and Rust: carthage.software

We help companies with:

  • Migration projects – upgrading PHP versions, modernizing legacy codebases, migrating frameworks
  • Custom development – building applications, APIs, and backend systems tailored to your requirements
  • Code quality improvement – helping teams adopt better development practices and tooling

Working with us helps fund continued development of Mago and other open-source projects.

Our Commitment to the Community

We understand that delaying the LSP is disappointing. We share that disappointment. We 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. We're committed to delivering exactly that, even if it takes longer than we 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:

← Retour au Blog