Lsp Laravel Package

Product Decisions This Supports

Developer Experience as a Platform Investment Laravel LSP is a zero-cost, zero-footprint lever for improving engineering throughput. Because it installs globally via Composer and never enters a project's composer.json, it requires no dependency review, no lockfile churn, no security sign-off on production artifacts, and no rollback plan. A PM can treat adoption as a trialable DX experiment rather than a platform migration — the cost of trying it is a single command per developer, and the cost of abandoning it is deleting that command.

Concrete decisions this informs:

• Build vs. buy vs. adopt for framework-aware tooling. If the roadmap contains an internal "Laravel IDE helper" or custom static-analysis effort, this package is the obvious substitute. It targets precisely the class of bug that generic PHP tooling misses: Laravel's string indirection. view('dashboard.index'), route('users.show'), config('services.stripe.key'), __('auth.failed'), env('DB_HOST'), Blade component names, Livewire components, Inertia pages, middleware aliases, storage disks, container bindings, validation rules, controller actions — all of these are strings whose correctness no PHP type system enforces. LSP turns them into navigable, diagnosed references. That is a defensible reason to deprioritize an in-house equivalent.
• Reduce the "stale string" defect class in the backlog. Missing views, mistyped translation keys, and removed env vars are the kind of defect that survives code review and fails late (in QA, or at runtime for the one branch nobody hit). Diagnostics on those references shift detection left, into the editor. Frame this as backlog reduction, not as tooling for its own sake: the measurable outcome is fewer trivial-but-embarrassing runtime errors per release.
• Onboarding time as a tracked metric. The features table reads as a map of Laravel's implicit knowledge: routes, views, config, env, translations, middleware, auth policies, bindings. A new hire no longer has to learn the directory layout by grep. This is a plausible input to a "time to first merged PR" metric for Laravel teams and a cheaper alternative to extensive written architecture docs for framework conventions.
• Editor policy: standardize the capability, not the editor. Official client extensions exist for VS Code, Cursor, Sublime Text, and Zed, plus documented configuration for Neovim 0.11+ and OpenCode. Product decision: don't mandate an editor to buy framework awareness. Publish a per-repo docs/editor.md (global install line + the two or three editor configs the team actually uses + a restart instruction) and let developers stay in their preferred tool. Mandating VS Code to obtain these features would forfeit the package's main advantage.
• Runtime-environment standardization. The phpEnvironment option (auto, herd, valet, sail, lando, ddev, local) with the phpCommand override is a diagnostic instrument disguised as a config flag. If most of the team must pin phpCommand to ["./vendor/bin/sail", "php"] to make indexing work, that is evidence your local-dev story is inconsistent. Treat recurring overrides as a signal to converge on one blessed environment rather than a per-developer workaround to document. Conversely, teams already on Sail or DDEV can ship a config that just works.
• Prioritizing what to enable first. Every feature flag defaults to true and can be turned off individually. This makes staged rollout possible per repo — start with routes, views, config, translations, env (highest-value, lowest-noise) and add Eloquent/Livewire/Inertia as confidence grows. It also lets you suppress noise in repos with heavy dynamic usage.
• Risk triage on monorepos and multi-app setups. The server finds the application by locating artisan, so "open the project root" is a hard operational requirement. If your repo layout is a monorepo with several Laravel apps or a container-mounted tree, that constraint is a real adoption blocker you can decide on up front, not discover mid-rollout.

When to Consider This Package

Good fit when:

• The team writes Laravel and Blade in earnest — the Blade navigation, diagnostics, and code actions are the differentiator versus generic PHP tooling, and Blade is where generic language servers go blind.
• You use Laravel's string-based conventions heavily: named routes, view names, translation keys, config keys, env vars, Livewire components, Inertia pages.
• You want framework awareness without changing editors, adding project dependencies, or altering CI.
• You are onboarding Laravel developers and want framework conventions discoverable in the editor rather than in a wiki.
• Your developers are on macOS (arm64/x64), Linux (arm64/x64), or Windows x64, and your team already has a working global Composer bin directory on PATH.
• You already use a PHP language server (e.g. Intelephense) — this complements rather than replaces it; expect to run both.

Look elsewhere or wait when:

• Production or CI use is implied. This is an interactive developer-tool binary. It speaks JSON-RPC over stdio and is meant to be launched by an editor. It has no role in builds, deploys, or pipelines.
• You need a hardened, versioned dependency contract. Install is global and unpinned; there is no per-project version, no lockfile entry, and therefore no reproducibility guarantee across machines. Teams that require pinned, auditable toolchains should treat this as best-effort DX, not infrastructure.
• Your platform mix is unsupported — e.g. Linux musl/Alpine dev containers, or Windows arm64.
• The repo isn't a single Laravel app rooted at artisan. Monorepo roots, nested apps, or heavily containerized mounts will need per-app editor config or won't attach at all.
• Your code relies on dynamic, computed string keys (config($someVariable), generated view names). Static analysis can't resolve those; diagnostics may be noisy or silent. Use per-feature flags to mute them.
• Your editor isn't covered. The supported set is VS Code, Cursor, Zed, Sublime Text, Neovim 0.11+, and OpenCode. Anything else (e.g. JetBrains/PhpStorm) gets no official client — PhpStorm users typically have alternative Laravel plugins already.
• You require a mature, well-established ecosystem. Signals are mixed: no dependent packages, a recent last release, and a young repo. It's an official Laravel project with real breadth, but adoption is early. Pilot with volunteers before mandating.
• Security review gates all tooling. Global install means a third-party binary executing project code paths (via the configured PHP command) on developer machines. Low risk, but a policy conversation for regulated environments.

Suggested adoption gate: pick one Laravel repo and three to five volunteers across at least two editors. Success criteria — the five canonical jumps resolve (view, route, config, __, env), a deliberately broken view('does.not.exist') produces a diagnostic, and Blade definition/code actions work. If those hold, expand per repo with the onboarding doc; if not, the failure is localized and cheap to reverse.

How to Pitch It (Stakeholders)

For executives (one paragraph): Laravel LSP is an official, open-source (MIT) language server that makes our editor understand Laravel. It adds autocomplete, hover documentation, error highlighting, and click-through navigation for the parts of Laravel that are written as plain strings — route names, view names, translation keys, config keys, environment variables, Blade and Livewire components, Inertia pages. Today those mistakes are caught late, in QA or production. With this, they're caught while typing. It installs in one command on each developer's machine, adds nothing to our application code or deployment, needs no new budget, and works across the editors our team already uses. We propose a small pilot on one repository before any broader rollout.

For engineering leaders: No dependency footprint and no CI change — it's a globally installed developer binary, not a project package. Zero production risk. Adoption is reversible in one command. Expected outcomes are fewer trivial runtime failures from stale strings, faster onboarding to Laravel conventions, and editor-level consistency without an editor mandate. Cost is a one-time onboarding step per developer plus a short per-repo docs/editor.md.

For engineers: It closes the gap generic PHP tooling leaves open. Go to Definition on view('dashboard.index') lands on the Blade file; hover on route('users.show', $user) shows the URI and verb; config(...), __(...), and env(...) jump to their sources; Blade and Livewire get completion and diagnostics; a typo'd view name gets flagged immediately instead of at runtime. Keep your current editor — official clients exist for VS Code, Cursor, Zed, and Sublime, and documented setup for Neovim 0.11+ and OpenCode. Three things to know: install globally with composer global require laravel/lsp and make sure Composer's global bin is on PATH; always open the Laravel project root (it finds the app via artisan); and restart your editor after configuring. If you use Sail, Lando, DDEV, Herd, or Valet, set phpEnvironment or phpCommand so indexing uses the right PHP runtime.

Anticipated objections:

• "Why not just use Intelephense?" — Keep it. It handles PHP; this handles Laravel's string indirection and Blade, which Intelephense can't resolve. They run side by side.
• "Is it stable enough to standardize on?" — Treat it as a supported developer convenience, not infrastructure: pilot first, per-repo opt-in, no production dependency, fully reversible. Version pinning is a known limitation of the global-install model.
• "Will it slow the editor down?" — It indexes the project on startup, so the first document may lag briefly; subsequent edits are incremental. Per-feature flags let you disable anything that misbehaves in a given repo.
• "What about monorepos / containers?" — Legitimate constraint. It needs a single app root at artisan. We scope the pilot to standard single-app repos and revisit monorepo support separately.
• "JetBrains users?" — No official client; those developers are out of scope for the pilot and keep their existing Laravel plugin. We don't mandate an editor to gain these features.