Official Laravel Zed Extension Brings LSP Support for PHP and Blade Files

Image: Art Institute of Chicago (via Laravel News)

By the end of this guide, you’ll have the official Laravel Zed extension installed and actively powering your PHP and Blade files with completions, diagnostics, and hover information drawn directly from your running application. No hacking around with generic PHP plugins. No hunting for community workarounds. First-class Laravel intelligence, built by the Laravel team, running inside Zed.

The Laravel team published the official Laravel Zed extension – the same language server technology revealed at Laracon US 2026 – directly to Zed’s extension registry. For PHP developers who’ve already switched to Zed from VS Code or PhpStorm, this is the missing piece.

Prerequisites

Image: Art Institute of Chicago (via Laravel News)

Before you begin, make sure the following are in place:

• Zed editor installed (version 0.150.0 or later – the extension API stabilised around this point)
• A working PHP installation – via Laravel Herd, Valet, Sail, Lando, DDEV, or a locally installed PHP binary
• An existing Laravel project – the language server is application-aware, so it needs a real Laravel codebase to index. If you’re new to the framework, our Laravel 12 Complete Guide for Beginners (2026) is the right starting point
• Basic familiarity with Zed’s command palette – you’ll use it to install the extension and restart the language server

You do not need to install anything Laravel-specific beforehand. The extension handles its own binary download automatically.

Step 1: Install the Extension

Open Zed, then press Cmd+Shift+X (macOS) or Ctrl+Shift+X (Linux/Windows) to open the Extensions panel. Search for Laravel and select the official entry listed under the laravel organisation – not the community alternatives.

Click Install. The extension downloads the Laravel LSP binary without any further input from you. There is no composer require, no Homebrew formula, no manual path configuration.

Expected result: The Install button changes to Uninstall and a version number appears beside the extension name. If the panel shows a download spinner that never resolves, check that your network isn’t blocking GitHub releases – that’s where the binary is fetched from.

The extension also checks for binary updates at most once every two hours, so your tooling upgrades itself between sessions rather than interrupting them.

Step 2: Open Your Laravel Project as the Workspace Root

Open your Laravel project folder as the workspace root in Zed (File > Open, then select the project directory itself – not a subfolder). If Zed can see your artisan file at the root level, the language server will locate it automatically.

Expected result: Within a few seconds of the project loading, you’ll see laravel-lsp appear in Zed’s status bar language server list. If the status bar shows no language server activity, double-check that you opened the project root rather than a nested folder – the server looks for artisan at the top level.

The Laravel LSP is application-aware, which is worth unpacking. Unlike a generic PHP language server that reads files and infers types statically, Laravel LSP runs PHP scripts inside your project to query the framework directly. It interrogates your service container bindings, your route table, your config files, and your translation strings at index time. Think of it like the difference between a mechanic who’s read a generic manual for your car’s make versus one who’s pulled up the full service history for your specific vehicle. The intelligence is contextual, not approximate.

Step 3: Verify Completions and Diagnostics Are Working

Open any .php file in your project. Type the following line and pause after the opening quote:

$value = config('');

An autocomplete dropdown should appear, populated with keys from your actual config files – app.name, mail.from.address, database.default, and so on. Select one and the string is completed for you.

Now test diagnostics. Add a reference to a view that doesn’t exist:

return view('layouts.nonexistent-template');

Within a moment, layouts.nonexistent-template should gain a diagnostic underline. Hover over it and you’ll see something like: View [layouts.nonexistent-template] not found. Delete the line and the error clears.

For Blade files, open any .blade.php template and type:

{{ route('') }}

Pause after the opening quote. The dropdown should list your named routes from routes/web.php and routes/api.php. Hover over an existing route name and you’ll see its URI and expected parameters.

Before the extension: these strings were opaque to the editor – no completions, no validation, just text. After the extension: every config key, route name, view path, and translation string in your application becomes navigable and verifiable in real time.

If the completions aren’t appearing, open Zed’s log panel (View > Debug > Open Log) and look for lines referencing laravel-lsp. A healthy startup looks like this:

[INFO] laravel-lsp: Starting language server
[INFO] laravel-lsp: Indexing project at /path/to/your/project
[INFO] laravel-lsp: Index complete (312 symbols)

If you see the start line but no index completion, your PHP environment likely needs manual configuration – covered in the next step.

Step 4: Configure phpEnvironment if Auto-Detection Fails

The phpEnvironment initialisation option controls how the language server locates a working PHP binary. The default value is "auto", which probes in this order: Laravel Herd, Valet, Sail, Lando, DDEV, then a locally installed PHP command.

For most macOS developers using Herd or a standard Homebrew install, "auto" works without any intervention. If you’re on Linux with PHP at a non-standard path, or using a Docker setup outside the Sail/DDEV/Lando list, you’ll need to override it.

Add the following to your Zed settings.json (Cmd+, to open it):

{
  "lsp": {
    "laravel-lsp": {
      "initialization_options": {
        "phpEnvironment": "php"
      }
    }
  }
}

Replace "php" with the full path to your binary if the command isn’t on your $PATH. For example:

"phpEnvironment": "/usr/local/bin/php8.3"

Common mistake – Docker setups: if your project runs inside a Docker container but Zed is running on your host machine, the language server runs on the host and needs a host PHP binary. It cannot reach inside a container to execute PHP. The simplest fix is to install PHP on the host machine as well – it doesn’t need to serve your application, it only needs to be callable by the language server for indexing purposes. Run which php on your host to confirm a binary is present, then set that path explicitly. If you strictly want to avoid installing PHP on the host, Lando and DDEV both expose a PHP binary the auto-detection probe can find – switching to either will resolve this without a manual path.

Save settings.json, then open the command palette and run > Restart Language Server.

Expected result: the log panel shows the index-complete line within 15-20 seconds. If you still see laravel-lsp: No PHP found, run which php in your terminal and verify the output path exactly matches what you’ve set in phpEnvironment.

Choosing Between the Official Extension and the Community Alternative

Two Zed extensions exist for Laravel, and they take fundamentally different approaches. The official Laravel Zed extension runs PHP scripts inside your project to query the framework directly. Mike Bronner’s community extension parses your files using tree-sitter – a syntax analysis tool – without ever executing any application code.

The community extension works without a running PHP environment and loads faster for that reason. The official extension provides deeper, application-aware intelligence because it can interrogate the live framework. Critically, the community extension’s own README advises against running both at once: two competing language servers will produce duplicate suggestions and unpredictable behaviour.

Pick one. For active Laravel projects where PHP is available locally, the official extension is the stronger choice.

Zed now joins Sublime Text, Cursor, and the official Laravel VS Code extension in the first-party support tier. If you work across editors, Neovim and OpenCode can point at the same Laravel LSP binary with a few lines of configuration, giving you consistent intelligence regardless of which editor you open.

Troubleshooting

Completions appear, but don’t include my routes or config keys.
The server may still be indexing, or it indexed before your project was fully bootstrapped. Open the command palette and run > Restart Language Server, then wait 15-20 seconds. If the issue persists, check that your .env file is present and your app can bootstrap without errors by running php artisan about in the terminal. Any bootstrap error will prevent the LSP from querying your application.

“laravel-lsp: No PHP found” in the log.
The auto-detection probe didn’t find a PHP binary in any of the expected locations. Run which php in your terminal, copy the output path, and set phpEnvironment to that value explicitly in settings.json as shown in Step 4. Docker users should see the Docker note in Step 4.

Duplicate completions appearing in Blade files.
Both the official extension and Mike Bronner’s community extension are active simultaneously. Open the Extensions panel (Cmd+Shift+X), disable one of them, and restart Zed. If you have a raw Intelephense setup also active, check whether it’s providing overlapping Blade completions and disable the conflict.

Extension shows as installed but nothing happens when I open a PHP file.
Check the language indicator in Zed’s status bar (bottom right of the window). If it reads Plain Text rather than PHP, Zed isn’t recognising the file type. You may need to associate .php files with the PHP language explicitly in your Zed settings.

What to Learn Next

With the Laravel Zed extension running, you’ve closed the IDE gap that previously pushed PHP developers back to VS Code or PhpStorm. From here, explore Livewire component workflows inside Zed – the extension completes component names and flags missing ones, making component-heavy UIs significantly faster to navigate.

If you’re coming from a Python background and want to compare the tooling ecosystem, our Python Django Full Stack Development guide offers a useful contrast to the Laravel approach. For developers setting up a PHP environment from scratch before graduating to Herd or Valet, our step-by-step guide to running PHP with XAMPP covers the foundations.

The extension is MIT-licenced and the source is available in the laravel/zed-extension GitHub repository if you want to understand how the binary integration works or contribute improvements.

If you’d like professional help configuring your Laravel development environment, onboarding a team to Zed, or building a Laravel application from the ground up, get in touch at drs-web.co.uk/contact.

Source: https://laravel-news.com/laravel-zed-extension