Laravel LSP lleva el contexto del framework a cualquier editorLaravel LSP lleva el contexto del framework a cualquier editor

El problema no es PHP, es el contexto de Laravel

Un editor puede conocer PHP y seguir perdido dentro de una aplicación Laravel. Las rutas, las vistas, las claves de configuración o las bindings del contenedor no son simples símbolos de PHP que un analizador genérico pueda resolver siempre. Ahí es donde un servidor de lenguaje específico del framework puede marcar una diferencia práctica.

Laravel LSP es la apuesta oficial para llevar ese contexto al protocolo que usan los editores. En lugar de atar estas capacidades a un único IDE, el proyecto expone completado, información al pasar el cursor, diagnósticos, enlaces a documentos, salto a definición y acciones de código para partes concretas de Laravel y Blade. (github.com)

Un servidor, no otra extensión cerrada

La parte interesante no es solo que sea oficial, sino que habla por stdio. Eso permite que el editor arranque el proceso y se comunique con él sin depender de una integración propietaria ni de un servidor HTTP adicional. La recomendación del proyecto es ejecutarlo desde la raíz de la aplicación Laravel siempre que sea posible. (github.com)

El repositorio documenta integración oficial para VS Code y Zed, y la extensión de VS Code también es compatible con Cursor. También hay configuración documentada para Neovim y OpenCode, así que no hay que cambiar de editor para probarlo. (github.com)

Qué entiende del proyecto Laravel

El alcance cubre rutas, vistas y Blade, traducciones, configuración, variables de entorno, assets, middleware, autorizaciones, bindings de aplicación, acciones de controladores y discos de almacenamiento. Además, contempla componentes de Livewire e información de páginas y propiedades de Inertia. No es una promesa genérica de “mejor soporte Laravel”: el README enumera qué capacidad ofrece cada área. (github.com)

Por ejemplo, las rutas tienen completado, hover, diagnósticos y enlaces navegables. Las claves de config() y las llamadas a env() cuentan con esas mismas ayudas, mientras que las vistas y Blade también disponen de acciones de código. Eloquent y las reglas de validación, en cambio, aparecen documentados únicamente con completado. (github.com)

Instalación y primer contacto

La instalación indicada es global mediante Composer. Después hay que asegurarse de que el directorio global de binarios de Composer esté incluido en el PATH, porque el editor ejecutará el comando laravel-lsp. No hace falta añadirlo como dependencia de cada proyecto para empezar a usarlo. (github.com)

composer global require laravel/lsp

En Neovim, la configuración oficial busca un archivo artisan para decidir la raíz del proyecto. Ese detalle evita que el servidor se levante en cualquier repositorio PHP que abras por accidente. También deja claro que la integración debe conocer el contexto de una aplicación Laravel, no solo una extensión de archivo. (github.com)

vim.lsp.config("laravel_lsp", {
    cmd = { "laravel-lsp" },
    filetypes = { "php", "blade" },
    root_dir = function(bufnr, on_dir)
        local root = vim.fs.root(bufnr, "artisan")
 
        if root then
            on_dir(root)
        end
    end,
})
 
vim.lsp.enable("laravel_lsp")

También encaja en proyectos con contenedores

Para quien trabaja con Sail o con entornos autocontenidos en el homelab, hay una opción relevante: phpEnvironment. Por defecto usa auto e intenta detectar Herd, Valet, Sail, Lando, DDEV y, como alternativa, PHP local. Si esa detección no encaja con tu entorno, puedes definir phpCommand con el comando y argumentos que deben ejecutar PHP. (github.com)

El orden importa: un phpCommand no vacío tiene prioridad sobre phpEnvironment. Eso permite apuntar explícitamente a ./vendor/bin/sail php cuando el proyecto vive detrás de Sail, en lugar de confiar en que el proceso del editor encuentre el binario correcto. Para una máquina de desarrollo remota o un contenedor persistente, esa previsibilidad vale más que una detección automática que funciona solo a veces. (github.com)

Configuración sin convertirlo en una caja negra

Las opciones llegan desde el cliente LSP mediante initializationOptions, y todas son opcionales. El servidor permite desactivar por separado capacidades como routeCompletion, configDiagnostics, envHover, inertiaLink o livewireComponentCompletion. Esto es útil si una característica concreta entra en conflicto con otra herramienta o no aporta valor al proyecto. (github.com)

También hay opciones orientadas a Pest: pestGenerateDocBlocks y pestHelperFilePath. La primera genera y mantiene actualizados los docblocks auxiliares cuando cambian los tests o los archivos de autoload de Composer. La segunda permite cambiar la ruta de salida, que por defecto es storage/framework/testing/_pest.php. (github.com)

La letra pequeña

No conviene vender Laravel LSP como si resolviera toda la inteligencia estática de una base de código PHP. La propia matriz de capacidades muestra límites concretos: Eloquent y las reglas de validación ofrecen completado, mientras que los componentes Livewire no anuncian diagnósticos ni acciones de código. Conviene probarlo junto al resto de herramientas del proyecto antes de retirar nada del flujo habitual.

Las acciones rápidas tampoco deben interpretarse como un corrector universal. La configuración documenta de forma explícita envViteQuickFix para variables de entorno, y el listado de funcionalidades indica acciones de código en vistas y Blade. Si esperas refactors globales, inferencia perfecta de tipos o arreglos automáticos para cualquier error de Laravel, ese no es el contrato publicado por el proyecto. (github.com)

Una mejora visible sin cambiar de editor

La ganancia real está en reducir cambios de contexto. Poder completar una ruta, abrir una vista, comprobar una clave de configuración o detectar una variable de entorno desde el editor evita búsquedas mecánicas por el proyecto. Son tareas pequeñas, pero se repiten demasiadas veces al día como para tratarlas como un detalle.

Me interesa especialmente porque no obliga a elegir entre el editor cómodo y el soporte específico de Laravel. Puedes usar VS Code, Cursor, Zed, Neovim u OpenCode, y mantener el mismo servidor como pieza común. Para proyectos locales y para stacks Laravel que viven dentro de un laboratorio doméstico, esa separación entre cliente y servidor es una decisión sensata.

Fuente: Laravel Magazine

Documentación oficial: laravel/lsp en GitHub (github.com)