A PHP IDE in Neovim 0.12+ comes down to five parts: a PHP language server, completion, syntax highlighting, linting on save, and formatting on save. Free servers now cover symbol rename and code actions without a paid licence, and every snippet below comes from my tested init.lua on Neovim v0.13.0-dev.
Key takeaways
- Best PHP LSP by budget: Intelephense Premium (30 EUR) reports errors in 53 ms; for free rename and code actions, PHPantom indexes 2,817 files in 0.65 s, while tuned Phpactor cuts error latency from 1.25 s to 342 ms.
- Neovim 0.12+ baseline: Native
vim.lsp.config()/vim.lsp.enable()and themainbranch ofnvim-treesitterreplace six legacy RPC and syntax plugins from 2017.- Lint & format traps solved: Pass
--no-interactiontophp-cs-fixerinconform.nvimso saves never create unwanted config files, and disable duplicatephpstanruns when using PHPantom.
The five parts of the stack are:
- Language server: Intelephense, Phpactor, or PHPantom for hover, definitions, references, rename, and code actions
- Completion & snippets: blink.cmp
- Syntax highlighting: nvim-treesitter
- Linting on save: nvim-lint with phpstan
- Formatting on save: conform.nvim with php-cs-fixer
Every code block below is an excerpt from my own init.lua, with settings for other languages left out.
How to navigate this guide:
- Fast setup: Check prerequisites, install a server with Mason, then add completion and Treesitter.
- Free vs. paid LSP choice: Start at Which PHP language server should you use? for the feature matrix and timings.
- Benchmark methodology: Jump to the Phpactor and PHPantom appendices at the bottom.
Which Neovim version, dependencies, and plugin manager do you need?
Neovim 0.12 or later and the php CLI on your PATH are the only required system dependencies. You also need a plugin manager such as lazy.nvim or built-in vim.pack. Node.js is required only for Intelephense. Both phpstan and php-cs-fixer are optional and resolve from vendor/bin first.
External CLI tools at a glance:
- PHP (
phpon yourPATH) - Node.js (only for Intelephense, installed via npm. Phpactor and PHPantom do not need Node.js.)
- phpstan (optional.
nvim-lintchecksvendor/bin/phpstanfirst, thenPATH.) - php-cs-fixer (optional.
conform.nvimchecksvendor/bin/php-cs-fixerfirst, thenPATH.)
On the editor side, the main branch of nvim-treesitter requires Neovim 0.12, while native LSP setup via vim.lsp.config() and vim.lsp.enable() arrived in Neovim 0.11. Neovim 0.12 also ships its own startup plugin manager, vim.pack (docs). The latest stable release is v0.12.6 (neovim/neovim, 2026-10-09), and I ran every test below on v0.13.0-dev.
Instead of vim.pack, I use lazy.nvim because it loads plugins on demand by file type, command, or key map. Put this bootstrap at the top of ~/.config/nvim/init.lua:
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not (vim.uv or vim.loop).fs_stat(lazypath) then
local lazyrepo = "https://github.com/folke/lazy.nvim.git"
local out = vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath })
if vim.v.shell_error ~= 0 then
vim.api.nvim_echo({
{ "Failed to clone lazy.nvim:\n", "ErrorMsg" },
{ out, "WarningMsg" },
{ "\nPress any key to exit..." },
}, true, {})
vim.fn.getchar()
os.exit(1)
end
end
vim.opt.rtp:prepend(lazypath)
require("lazy").setup({
-- the plugin specs from the next sections go here
})
Plugin specs shaped like { "saghen/blink.cmp", ... } in the sections below go inside require("lazy").setup({ ... }), while standalone Lua calls such as vim.lsp.config() and vim.api.nvim_create_autocmd() sit below it in init.lua.
Which PHP language server should you use?
Choose Intelephense if you own or buy the 30 EUR Premium licence, because it reports the first diagnostic in 53 ms and includes every IDE feature. For a free PHP language server with rename and code actions, start with PHPantom for sub-second indexing or tuned Phpactor for 342 ms diagnostics.
My own config runs PHPantom at the moment, with 'intelephense' and 'phpactor' commented out in ensure_installed. When I bought my Intelephense licence years ago, it was the only usable PHP LSP with a broad feature set. If you want a free server for a large codebase, try both PHPantom and tuned Phpactor first. PHPantom indexes cold codebases much faster, though it is younger and reports its first diagnostic after 0.5 to 1 s. Already picked a server? Skip ahead to setting it up in Neovim.
How do Intelephense, Phpactor, and PHPantom compare?
Across a 7-file PHP test project and a 2,817-file legacy application, all three servers handle hover, go to definition, references, and completion, while unlicensed Intelephense omits rename and code actions. PHPantom leads cold indexing at 0.65 s and 286 MB of RAM, whereas Intelephense leads diagnostic latency at 53 ms.
I ran Intelephense and Phpactor on the same 7-file scratch project (one interface, one broken method call, and one syntax error). I tested PHPantom in a later session on a rebuilt project of the same shape, so its column is a close guide rather than the exact same run (Phpactor methodology, PHPantom methodology). The final three rows of the performance table measure a legacy application with 2,817 PHP files and no vendor folder:
Performance and RAM
| Metric | Intelephense 1.18.5, Premium | Intelephense 1.18.5, no licence | Phpactor 2026.10.07.0 | PHPantom 0.11.1 |
|---|---|---|---|---|
| First definition answer, warm | 271 ms (264 to 348) | 272 ms (266 to 331) | 132 ms (121 to 153) | 187 ms (171 to 221), no cache on disk |
| First definition answer, empty cache | 518 ms (487 to 604) | 511 ms (498 to 581) | 2.4 s (2.4 to 2.7) | 187 ms (171 to 221), no cache on disk |
| First diagnostic after opening a file, warm cache | 53 ms (48 to 65) | 51 ms (48 to 61) | 1.12 s (1.10 to 1.13) | 973 ms right after the first answer, 506 ms (505 to 509) once the server ran for 3 s |
| Index of 2,817 PHP files, empty cache | 2.0 s (1.8 to 2.5) | Not measured | 6.3 s (5.9 to 7.0) | 0.65 s (0.60 to 0.72) |
| Index of 2,817 PHP files, warm cache | 0.4 s | Not measured | 0.2 s | 0.65 s again, no warm start |
| Peak memory, index with empty cache | 574 MB | Not measured | 915 MB | 286 MB (279 to 307) |
When to skip a server based on these numbers:
- Skip unlicensed Intelephense if you use LSP rename or code actions, because both require the 30 EUR Premium licence.
- Skip PHPantom if you rely on sub-500 ms diagnostics when opening a file (it lands at 506 to 973 ms, with no documented sleep-time setting).
- Skip default Phpactor on RAM-constrained laptops with large codebases (915 MB peak across 8 workers), unless you set
indexer.parallel_workersto1(192 MB peak, at the cost of a 14.7 s cold index).
Feature matrix
| Feature / Output | Intelephense 1.18.5, Premium | Intelephense 1.18.5, no licence | Phpactor 2026.10.07.0 | PHPantom 0.11.1 |
|---|---|---|---|---|
| Price | One-off fee (30 EUR personal) | Free | Free (MIT license) | Free (MIT license) |
| Hover, definition, references, completion | Work | Work | Work | Work |
Rename run to execute | 2 edits in 2 files | Not offered | 2 edits in 2 files | 2 edits in 2 files |
Type definition of $this->bar | BarInterface.php:7 | Not offered | BarInterface.php:7 | BarInterface.php:7 |
Implementation of BarInterface | Impl.php:7 | Not offered | Impl.php:7 | Impl.php:7 |
Code actions on Impl.php (class without the interface method) | “Add PHPDoc for ‘App\Impl’”, “Implement all abstract methods for ‘Impl’” | Not offered | Decorate "App\BarInterface", “Implement contracts” | “Implement run” |
Code actions on User.php (unimported Foo) | “Add PHPDoc for ‘App\Other\User’”, “Add PHPDoc for ‘make’”, “use App\Foo” | Not offered | Import class "App\Foo", “Extract method” | “Import App\Foo”, “Extract interface” |
| Call to a missing method, line 15 | Undefined method 'missing'. | Undefined method 'missing'. | Method "missing" does not exist on interface "App\BarInterface" | Method 'missing' not found on class 'App\BarInterface' |
| Syntax error, line 7 | Unexpected ';'. | Unexpected ';'. | The parse error text of PHP itself | Syntax error: unexpected token `;` |
| Capabilities the server advertises at start | 21 | 9 | 15 | 23 |
Licensed Intelephense includes six features that Phpactor lacks (code lens, inlay hints, folding ranges, document links, type hierarchy, and go to declaration), while Phpactor includes six that unlicensed Intelephense locks behind Premium (code actions, execute command, implementation, rename, selection range, and type definition).
PHPantom covers Phpactor’s free refactoring set (rename, type definition, implementation, and code actions) plus five of the six Intelephense Premium extras: code lens, inlay hints, folding ranges, document links, and type hierarchy. Only go to declaration is missing in 0.11.1 (Method not found). The count of 23 leaves out type hierarchy, because that one worked in my test despite not appearing in the startup capability list.
Small-project timings are medians of 15 runs. The two Intelephense columns match within measurement spread, so the licence key does not affect speed. The Phpactor numbers use the PHAR on PATH. Big-project index rows are medians of 5 runs for Intelephense and Phpactor, and 6 runs for PHPantom.
Which Intelephense features need a Premium licence?
Rename and code actions require the Intelephense Premium licence (intelephense.com, 2026-11-02). A personal licence costs a one-off fee of 30 EUR, and a business licence costs 65 EUR per user. Without a licence you still get hover, go to definition, find references, completion, signature help, and diagnostics.
In an unlicensed session, Neovim rejects rename requests with textDocument/rename is not supported. Code action menus come back empty. Beyond rename and code actions, Premium unlocks code folding, find all implementations, go to type definition, go to declaration, smart select, code lens, type hierarchy, inlay hints, and document links.
Drop your Premium key into ~/intelephense/licence.txt and Intelephense activates it automatically. It greets you with Your Intelephense licence key has been activated. If you prefer an explicit path, nvim-lspconfig documents a licenceKey option that accepts either the key string or a file path.
Is Phpactor fast and accurate enough?
Phpactor is a free, MIT-licensed PHP language server written in PHP. It provides rename, type definition, implementation lookup, and code actions at no cost. Lowering its diagnostic sleep time cuts error reporting from 1.12 s to 342 ms (docs). Cold indexing on 2,817 files still takes 6.3 s against Intelephense’s 2.0 s.
Phpactor’s own README opens with a candid disclaimer: “This language server may not be the one you’re looking for.” The maintainer lists “some short-comings in regards to performance, accuracy and maintainability”, while highlighting its strength in code actions. A 7-file project hides indexing bottlenecks, so the Phpactor appendix benchmarks the 2,817-file codebase. I have not tested accuracy.
Once the index cache is warm, Phpactor answers definition lookups in 132 ms against Intelephense’s 271 ms. It reloads the 2,817-file index in 0.2 s against 0.4 s. On an empty cache, Intelephense wins both first definition (0.5 s vs. 2.4 s) and first diagnostic (44 ms vs. 1.13 s).
How fast is PHPantom on small and large codebases?
PHPantom is a free, MIT-licensed PHP language server written in Rust. It parses PHP with Mago and ships as a static binary that needs neither Node.js nor PHP. Version 0.11.1 (2026-10-07) answers small-project definitions in 187 ms and cold-indexes 2,817 files in 0.65 s using 286 MB of RAM.
In the 7-file project, PHPantom finished initialization in 53 ms and wrote no index cache to disk. Every start reads the files fresh. Diagnostics lagged behind definitions: 973 ms right after the first answer, and 506 ms once the server had run for 3 s. No documented setting shortens that delay. If you pair PHPantom with phpstan or php-cs-fixer, see its two config catches below.
On the 2,817-file legacy application (no vendor folder), PHPantom parsed 2,816 of the 2,817 files in 0.65 s and peaked at 286 MB. Cold Intelephense needed 2.0 s and 574 MB, and cold Phpactor needed 6.3 s and 915 MB. Because PHPantom keeps no disk cache, warm restarts of Phpactor (0.2 s) and Intelephense (0.4 s) beat its 0.65 s restart. PHPantom’s own benchmark on a 5.1K-file Laravel codebase shows the same gap: 2 s until ready, against 11 s for Intelephense and 1 min 34 s for Phpactor.
How do you set up a PHP language server in Neovim?
A language server (LSP, short for Language Server Protocol) is an external program that answers editor queries about your PHP code: hover types, symbol definitions, and references. Because Neovim ships no PHP server, setup takes two steps: installing the server binary and enabling it through Mason or Neovim’s native vim.lsp.enable() API.
How do you set up a server with Mason?
Mason installs PHP language servers into ~/.local/share/nvim/mason/packages and places launcher scripts inside ~/.local/share/nvim/mason/bin, which mason.setup() adds to Neovim’s internal PATH. Pairing Mason with mason-lspconfig automatically installs and enables every server listed in ensure_installed, so uncommenting one entry gets Intelephense, Phpactor, or PHPantom running.
My real list includes servers for other languages alongside PHP - below you see the PHP-relevant parts:
require('mason').setup({})
require('mason-lspconfig').setup({
ensure_installed = {
'intelephense', -- or
-- 'phpactor', -- or
-- 'phpantom_lsp',
},
})
Because mason-lspconfig defaults to automatic_enable = true, you need no vim.lsp.enable() call when using Mason. nvim-lspconfig supplies the start command, file types, and project root markers for each server:
intelephense: runsintelephense --stdio(installed via npm). Matches.gitandcomposer.json.phpactor: downloadsphpactor.pharfrom GitHub releases (same SHA-256 as a manual download) and wraps it inphp phpactor.phar. Runsphpactor language-serverwith root markers.git,composer.json,.phpactor.json, and.phpactor.yml.phpantom_lsp: runsphpantom_lsponphpandbladebuffers. Matches.phpantom.toml,.git, andcomposer.json.
How do you set up a server without Mason?
Setting up a PHP language server without Mason takes two manual steps: placing the server executable onto your shell PATH and registering it in init.lua with Neovim 0.11’s built-in vim.lsp.config() and vim.lsp.enable() functions. Run which in your shell to verify Neovim can find the binary.
First, install the executable for the server you picked:
- Intelephense: install globally with npm:
npm install -g intelephense
- Phpactor: download
phpactor.pharfrom the Phpactor release page, rename it tophpactor, and runchmod +x. Move it to a folder on yourPATHsuch as~/.local/bin. Because the PHAR starts with#!/usr/bin/env php, it needs no wrapper script. - PHPantom: install via
cargo install phpantom_lsp --locked, Homebrew, or a pre-built binary from the PHPantom release page.
Second, configure and activate the server in init.lua. Without nvim-lspconfig, describe the server in three fields before calling vim.lsp.enable(). Swap the binary name and root markers if you chose phpactor or phpantom_lsp:
vim.lsp.config('intelephense', {
cmd = { 'intelephense', '--stdio' },
filetypes = { 'php' },
root_markers = { '.git', 'composer.json' },
})
vim.lsp.enable('intelephense')
cmdsets the start command.filetypesselects which buffers attach.root_markerstells Neovim how to walk up the directory tree to find the project root.
Calling vim.lsp.enable('intelephense') alone without those three fields attaches nothing unless nvim-lspconfig is installed.
If you install nvim-lspconfig without Mason, omit the vim.lsp.config() block. Call vim.lsp.enable('intelephense'), vim.lsp.enable('phpactor'), or vim.lsp.enable('phpantom_lsp') directly. My own config uses that pattern for TypeScript: vim.lsp.enable('tsc') runs the project’s tsc --lsp, leaving nothing for Mason to install.
How do you speed up Phpactor diagnostics in Neovim?
Phpactor waits 1,000 ms before it analyses a file again by default, pushing the first diagnostic after opening a PHP file to 1.25 s. Passing a 100 ms diagnostic_sleep_time via --config-extra in vim.lsp.config() cuts that wait to 342 ms and avoids any .phpactor.json project trust prompt.
vim.lsp.config('phpactor', {
cmd = { 'phpactor', 'language-server', '--config-extra={"language_server.diagnostic_sleep_time":100}' },
})
That override works on both installation routes because Mason puts its bin folder on PATH. Without Mason, add vim.lsp.enable('phpactor') right below it. With mason-lspconfig, leave vim.lsp.enable() out. In my tests, the tuned command cut first-diagnostic latency from 1,255 ms to 342 ms with the PHAR on PATH. Through Mason, it dropped from 1,247 ms to 344 ms (benchmark details).
Mason or vanilla: which one should you use?
Use Mason if you work across multiple languages, because one ensure_installed list bootstraps every language server automatically on a new machine. Use vanilla vim.lsp.enable() if PHP is your only language, if you prefer fewer plugins, or if your system package manager already manages the binary.
| What | Mason | Vanilla |
|---|---|---|
| Plugins | mason.nvim, mason-lspconfig.nvim and nvim-lspconfig | None, or nvim-lspconfig alone |
| Install a server | One line in ensure_installed, or the :Mason window | The tool that fits the server, for example npm install -g intelephense and all your other servers (and package managers) |
| Start a server | mason-lspconfig enables it | vim.lsp.enable('intelephense') |
| Start command and root markers | nvim-lspconfig | Also nvim-lspconfig, or three fields in vim.lsp.config() |
| Where the files live | ~/.local/share/nvim/mason/packages | Wherever npm, cargo, Homebrew or your package manager put them |
| Update | U in the :Mason window | npm update -g intelephense (and various other commands for your other servers) |
| Node version manager | The copy stays in mason’s folder. It still needs node on the PATH. | With fnm, global npm packages belong to one Node version. |
Both routes end with the same Neovim LSP client talking to the same server process. My own config mixes both: Mason for most servers and one vim.lsp.enable line for tsc. Everything in the rest of this guide works identically on both routes.
How do you check that the server runs?
Open a PHP file inside a project folder that contains .git or composer.json, then run :checkhealth vim.lsp to verify that your PHP language server appears under Active Clients with the expected root directory. Pressing K on any PHP symbol confirms that hover documentation works.
Neovim binds K to vim.lsp.buf.hover() automatically whenever a server attaches, provided you have no custom K map or keywordprg (:help lsp-defaults). I keep the default K binding.
Once your language server attaches, the next two sections turn its data into an autocompletion menu and replace Vim’s old regular-expression syntax files with Treesitter parsers.
How do you get PHP completion and snippets in Neovim?
blink.cmp provides the autocompletion popup and signature-help window in Neovim, pulling PHP symbols and method signatures directly from your active language server. Pairing it with LuaSnip and friendly-snippets adds ready-made PHP and PHPDoc snippet templates from php.json and phpdoc.json.
My blink.cmp spec for lazy.nvim:
{
"saghen/blink.cmp",
version = "1.*", -- release tags ship a prebuilt fuzzy matcher
opts = function()
local function has_words_before()
local col = vim.api.nvim_win_get_cursor(0)[2]
return col ~= 0 and vim.api.nvim_get_current_line():sub(col, col):match("%s") == nil
end
return {
keymap = {
preset = "none",
["<CR>"] = { "accept", "fallback" },
["<Tab>"] = {
"select_next",
"snippet_forward",
function(cmp) if has_words_before() then return cmp.show() end end,
"fallback",
},
["<S-Tab>"] = { "select_prev", "snippet_backward", "fallback" },
},
completion = {
list = { selection = { preselect = false } }, -- <CR> only accepts an item you picked
documentation = { auto_show = true }, -- the docs pop up by themselves
},
cmdline = { enabled = false }, -- keeps blink.cmp out of the : command line
snippets = { preset = "luasnip" },
sources = { default = { "lsp", "snippets", "buffer", "path" } },
signature = { enabled = true },
}
end,
}
And the LuaSnip block for lazy.nvim:
{
"L3MON4D3/LuaSnip",
event = "InsertEnter",
dependencies = { "rafamadriz/friendly-snippets" },
build = "make install_jsregexp",
config = function()
require("luasnip.loaders.from_vscode").lazy_load()
end,
}
In my key maps <Tab> has three jobs: select the next item, jump to the next snippet field, or open the menu after a word. <CR> accepts only an item you picked (preselect = false). The real spec has more maps, like <C-y> to accept and <C-u> and <C-d> to scroll the docs.
Signature help, the popup showing a function’s parameters while you type arguments, is free in Intelephense as well as Phpactor and PHPantom, and signature = { enabled = true } switches on blink.cmp’s window for it. Next, Treesitter upgrades how Neovim parses and colors the PHP buffer itself.
How do you highlight PHP with Treesitter?
nvim-treesitter highlights PHP and PHPDoc with real parsers instead of regular expressions. It replaces the syntax file from the 2017 post, php.vim, which is archived now (last push 2020-05-28). I use the main branch, which can’t be lazy-loaded, so the spec says lazy = false.
This installs the two PHP parsers and starts Treesitter for every file type that has one:
{
"nvim-treesitter/nvim-treesitter",
branch = "main",
lazy = false, -- the main branch does not support lazy-loading
build = ":TSUpdate",
config = function()
local ts = require("nvim-treesitter")
ts.install({ "php", "phpdoc" })
vim.api.nvim_create_autocmd("FileType", {
callback = function(ev)
local lang = vim.treesitter.language.get_lang(ev.match)
if not lang then
return
end
if not pcall(vim.treesitter.start, ev.buf, lang) then
-- parser missing: install it, highlighting starts on the next open
if vim.tbl_contains(ts.get_available(), lang) then
ts.install(lang)
end
return
end
if vim.treesitter.query.get(lang, "indents") then
vim.bo[ev.buf].indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()"
end
end,
})
end
},
My full install list has 38 parsers, and build = ":TSUpdate" runs whenever lazy.nvim installs or updates the plugin. If the parser for a file type is missing, the autocmd installs it, and highlighting applies the next time you open the file.
I also load nvim-treesitter-context with max_lines = 0 (no limit) and mode = "topline". Whenever the opening line of a long class, method declaration, or if block scrolls above the viewport, it stays pinned at the top of the window:
With completion and syntax highlighting running, the remaining two core plugins enforce your project’s static analysis and code style rules whenever you save.
How do you lint PHP in Neovim?
nvim-lint runs phpstan every time you save a PHP buffer and turns its output into Neovim diagnostics, catching type-level bugs such as calls to undefined methods. My spec leaves php -l out on purpose because all three language servers already flag syntax errors (comparison below):
{
"mfussenegger/nvim-lint",
event = "VeryLazy",
config = function()
require('lint').linters_by_ft = {
php = { 'phpstan' },
}
vim.api.nvim_create_autocmd({ "BufWritePost" }, {
callback = function()
-- try_lint without arguments runs the linters defined in `linters_by_ft`
-- for the current filetype
require("lint").try_lint()
end,
})
end
},
The linter runs on BufWritePost, so nothing runs while you type. Behind the scenes, nvim-lint calls phpstan analyze --error-format=json --no-progress and preserves phpstan’s rule identifier on each diagnostic.
In the scratch project (phpstan.neon at level: 6), calling $this->bar->missing(3) on line 15 produced Call to an undefined method App\BarInterface::missing(). from phpstan (code method.notFound) after 683 ms. Intelephense flagged the same line with Undefined method 'missing'., so line 15 shows two agreeing diagnostics:
How do you format PHP on save in Neovim?
conform.nvim runs php-cs-fixer automatically whenever you save a PHP buffer, reading your project’s style rules from .php-cs-fixer.dist.php. Setting lsp_format = "fallback" tells Neovim to format through the language server on save only when php-cs-fixer is unavailable, so LSP formatters never override project rules.
{
'stevearc/conform.nvim',
event = "BufWritePre",
cmd = "ConformInfo",
config = function()
require("conform").setup({
formatters_by_ft = {
php = { "php_cs_fixer" },
},
format_on_save = {
lsp_format = "fallback",
},
})
-- Without a project config php-cs-fixer asks to create one. Neovim answers yes, so the first save
-- writes .php-cs-fixer.dist.php and .gitignore into the project and formats nothing.
require("conform").formatters.php_cs_fixer = {
append_args = { "--no-interaction", "--using-cache=no" },
}
end
},
The append_args override at the bottom prevents a nasty surprise. Without a project config file, php-cs-fixer prompts to create one, and Neovim answers yes. The first save then writes .gitignore and .php-cs-fixer.dist.php into your repository and leaves the buffer unformatted. Passing --no-interaction writes no extra files and formats with the default rules.
On save, conform.nvim runs php-cs-fixer and nothing else. I previously set lsp_format = "last" on the PHP entry. That did nothing on save because format_on_save overrides the file-type setting, so I dropped it. With PHPantom attached, saving kept the double quotes from my php-cs-fixer rules. Avoid "last" with PHPantom anyway, because its built-in formatter would undo those rules (details below).
Here is a messy test file before saving:
<?php
declare(strict_types=1);
namespace App;
class Messy {
public function name() : string { return "messy"; }
}
After saving with @PSR12 and single_quote in .php-cs-fixer.dist.php, the buffer looks like this:
<?php
declare(strict_types=1);
namespace App;
class Messy
{
public function name(): string
{
return 'messy';
}
}
Style rules come from --rules or a config file (see the PHP CS Fixer config docs). The --level=symfony flag from the 2017 post no longer exists.
Do you need nvim-lint and conform.nvim if you have an LSP?
A PHP language server alone handles syntax checks, basic type errors, and default code formatting without extra plugins. You only need nvim-lint when your project enforces stricter static analysis via phpstan.neon, and conform.nvim when your repository defines custom formatting rules in .php-cs-fixer.dist.php.
Intelephense reports syntax errors, flags type errors, and formats code without a licence. Phpactor does the same once you enable its phpstan and php-cs-fixer integrations. I tested all three servers on two deliberate bugs (return 42 in a string method and strlen(5)), which phpstan reports as return.type and argument.type. Intelephense flagged both regardless of licence (Expected type 'string'. Found 'int'. and Expected type 'string'. Found '5'.). PHPantom flagged both natively, and Phpactor reported neither by default.
Formatting differs more across the servers. Intelephense formats Messy above, yet keeps "messy" in double quotes because it ignores .php-cs-fixer.dist.php. Phpactor disables formatting by default. The snippet below replaces the earlier vim.lsp.config('phpactor', ...) block so the 100 ms sleep time and both tool integrations stay in one JSON object:
vim.lsp.config('phpactor', {
cmd = { 'phpactor', 'language-server', '--config-extra={"language_server.diagnostic_sleep_time":100,"language_server_phpstan.enabled":true,"language_server_php_cs_fixer.enabled":true}' },
})
With both switches enabled, Phpactor surfaced the two phpstan errors, and vim.lsp.buf.format matched the conform.nvim output above, single quotes included. Because my scratch project had no vendor/bin, I also pointed language_server_phpstan.bin and language_server_php_cs_fixer.bin at my global binaries (the default looks in vendor/bin, which I did not test). First-diagnostic time stayed at 371 to 392 ms across 3 runs through Mason.
Does PHPantom run phpstan and php-cs-fixer for you?
PHPantom checks PHP types natively and runs phpstan automatically whenever phpstan is on your PATH, duplicating diagnostics if nvim-lint also runs phpstan. For code formatting, PHPantom runs its own built-in formatter by default and delegates to php-cs-fixer only when configured in .phpantom.toml.
On the two type bugs above, PHPantom reported type_mismatch_return and type_mismatch_argument natively. Because the scratch project had phpstan.neon (level 6) and phpstan on PATH, it also ran phpstan on its own and showed return.type and argument.type alongside them. If you keep nvim-lint enabled, turn off PHPantom’s built-in phpstan runner in .phpantom.toml (in the project root or globally in ~/.config/phpantom_lsp/) so phpstan does not run twice:
[phpstan]
command = ""
Formatting with PHPantom has a similar catch. Calling vim.lsp.buf.format ran PHPantom’s built-in formatter, which ignored single_quote = false in .php-cs-fixer.dist.php and turned "messy" into 'messy'. Tell PHPantom to delegate formatting to php-cs-fixer in .phpantom.toml:
[formatting]
php-cs-fixer = "php-cs-fixer"
With that entry, formatting kept "messy" in double quotes as configured. The PHPantom docs state that listing php-cs-fixer under require-dev in composer.json enables it automatically, yet adding require-dev alone changed nothing in my vendor-less scratch project. I have not tested a real vendor/bin/php-cs-fixer yet. Also avoid setting lsp_format = "last" in conform.nvim: a manual require('conform').format() call ran php-cs-fixer first, and PHPantom’s built-in formatter then overwrote "messy" with 'messy'.
In short, start with your language server alone, then add nvim-lint for project phpstan.neon rules and conform.nvim for .php-cs-fixer.dist.php configs. Those five pieces complete the core PHP IDE. The next three sections cover optional daily-workflow plugins from my config for previewing references, marking PHPUnit test coverage, and previewing refactors.
How do you jump to definitions and references in PHP?
Your PHP language server resolves definitions, references, type definitions and implementations directly. PHP projects need no ctags files or Git hooks anymore. Binding gd, gr, gD and gi inside the LspAttach autocommand opens glance.nvim preview windows only when a server attaches.
Because LspAttach sets these key maps per buffer, gd and gr keep their built-in Vim meaning in files without a language server:
vim.api.nvim_create_autocmd('LspAttach', {
desc = 'LSP actions',
callback = function()
local bufmap = function(mode, lhs, rhs)
vim.keymap.set(mode, lhs, rhs, { buffer = true })
end
-- glance, per buffer so gd/gD/gi keep their built-in meaning without an LSP client.
-- <leader>nd/nr/nD/ni open the same lookups in the snacks picker.
bufmap('n', 'gd', '<CMD>Glance definitions<CR>')
bufmap('n', 'gr', '<CMD>Glance references<CR>')
bufmap('n', 'gD', '<CMD>Glance type_definitions<CR>')
bufmap('n', 'gi', '<CMD>Glance implementations<CR>')
bufmap('n', '<leader>F', vim.lsp.buf.format)
bufmap('n', 'gl', vim.diagnostic.open_float)
bufmap('n', '<c-p>', function() vim.diagnostic.jump({ count = -1, float = true }) end)
bufmap('n', '<c-n>', function() vim.diagnostic.jump({ count = 1, float = true }) end)
end
})
gD and gi require the Intelephense Premium licence too, because “Go to type definition” and “Find all implementations” are Premium features. Phpactor and PHPantom offer both without a licence.
The gr map has one catch. Neovim 0.11+ maps grr, grn, gra, and gri by default, so pressing gr waits for a third key until timeoutlen expires (1,000 ms by default). In a clean Neovim session with a buffer-local gr map, Glance opened 1,056 ms after I pressed gr. Passing nowait = true in the map options skips the delay, at the cost of disabling grn, gra, and gri in that buffer.
gl opens the diagnostic float. <c-n> and <c-p> jump to the next or previous diagnostic with the float open. <leader>F formats the buffer via the language server (my leader key is Space). <leader>nd, <leader>nr, <leader>nD, and <leader>ni run the same four symbol lookups inside the snacks.nvim picker when I want every match listed in one searchable window:
How do you run PHP tests from Neovim?
Instead of running PHPUnit inside Neovim with neotest, vim-test, or nvim-dap, a minimal setup runs tests in a terminal. One key map (<leader>na in ftplugin/php.vim) switches between a PHP class and its test, while nvim-coverage marks covered lines from coverage/cobertura.xml.
The function behind <leader>na maps src/ to tests/, appends Test to the file name, and creates the test folder when missing (an older post shows the original function).
In my config, nvim-coverage loads for go and php. Out of the box, :CoverageLoad failed on PHP with this error:
module 'xmlreader' not found
The plugin README lists the Lua rock lua-xmlreader as “needed for PHP when using the cobertura parser”. Because lua-xmlreader is a C module and nvim-coverage ships no rockspec, lazy.nvim never installs it automatically. Compiling it requires luarocks and the libxml2 headers (apt install luarocks libxml2-dev). Adding a build function that installs the rock into its own folder, plus a package.cpath entry in config, fixes it:
local coverage_rocks = vim.fn.stdpath("data") .. "/coverage-rocks"
{
"andythigpen/nvim-coverage",
ft = { "go", "php" },
dependencies = "nvim-lua/plenary.nvim",
-- The PHP cobertura parser needs the C rock lua-xmlreader. The plugin ships no rockspec, so lazy.nvim
-- does not install it. The build needs luarocks and the libxml2 headers (apt: luarocks libxml2-dev).
build = function()
if vim.fn.executable("luarocks") == 0 then
vim.notify("nvim-coverage: luarocks not found, PHP coverage needs lua-xmlreader", vim.log.levels.WARN)
return
end
local res = vim.system({ "luarocks", "--lua-version", "5.1", "--tree", coverage_rocks, "install", "lua-xmlreader" }, { text = true }):wait()
if res.code ~= 0 then
vim.notify("nvim-coverage: installing lua-xmlreader failed:\n" .. res.stderr, vim.log.levels.ERROR)
end
end,
config = function()
package.cpath = package.cpath .. ";" .. coverage_rocks .. "/lib/lua/5.1/?.so"
require("coverage").setup()
end,
},
lazy.nvim runs build on install or update. If the plugin is already installed, run :Lazy build nvim-coverage once (3 s on my machine). :Coverage then reads file paths from <package name="..."> and places signs in the gutter. Green bars mark executed lines, and red bars mark unreached ones:
How do you refactor and document PHP code in Neovim?
PHP symbol renaming and code actions come from your language server: free in Phpactor and PHPantom, or via the Premium licence in Intelephense. Neovim 0.11+ binds grn for rename and gra for code actions out of the box, while optional UI plugins add live rename and action previews.
I layer two preview plugins on top of Neovim’s built-in bindings:
- inc-rename.nvim (
<leader>rn) previews a symbol rename live across every file while you type in the command line. - actions-preview.nvim (
<leader>ca) opens a picker to inspect code actions before applying them.
In the scratch project, Intelephense offered these code actions:
- Implementing
BarInterfacewithoutrunoffered “Implement all abstract methods for ‘Impl’”. - Calling
new Foo()without an import offered “use App\Foo”. - Placing the cursor on a class or method offered “Add PHPDoc for ‘make’”.
Three quirks to expect with actions-preview.nvim:
- The diff preview pane stays empty for Intelephense actions because the server responds with workspace commands rather than text edits (
Preview is not available for this action (command=intelephense.import.symbol)). - Phpactor’s import action is a command too (
name_import), so its preview pane stays empty as well. - When
laststatusis2, the status line inside the plugin’s input window steals one row and hides the first action. The screenshot below useslaststatus=3.
LSP code actions replace vim-php-refactoring-toolbox and the custom Phpactor mappings from 2017, while PHP 8.0 constructor property promotion retired my old “constructor magic” snippet.
For generating and updating PHPDoc blocks, my config still loads php-doc-modded, the successor to PDV from my PHPDoc post. Pressing <leader>rd (mapped in ftplugin/php.vim) regenerates the docblock above the current method:
What replaced the 2017 plugins?
Of all the plugins in the 2017 Neovim PHP guide, only php-doc-modded remains in my 2026 configuration, while native LSP clients, Treesitter, blink.cmp, nvim-lint, and conform.nvim replaced the rest. When I wrote the first version of this post on November 5, 2017, getting a completion popup took six plugins (ncm2, nvim-yarp, vim-hug-neovim-rpc, phpactor, ncm2-phpactor, and ncm2-ultisnips)—two of those repositories are archived now. The migration table below pairs each 2017 plugin with its modern replacement and its GitHub repository status on 2026-11-02.
| 2017 plugin | In my config now | Status of the 2017 repository |
|---|---|---|
| vim-plug | lazy.nvim | Last push 2026-10-15 |
| UltiSnips and phux/vim-snippets | LuaSnip and friendly-snippets | UltiSnips 2026-09-06 |
| ncm2, nvim-yarp, vim-hug-neovim-rpc | blink.cmp | ncm2 2025-06-07, nvim-yarp 2022-06-08, vim-hug-neovim-rpc 2021-05-15 and archived |
| phpactor Vim plugin with ncm2-phpactor | PHPantom, earlier Intelephense | ncm2-phpactor 2023-02-02 |
ctags Git hook, vim-easytags, vim-gutentags | LSP definitions and references | easytags 2019-10-01, gutentags 2024-06-09 |
| php.vim | nvim-treesitter | 2020-05-28 and archived |
| ale | nvim-lint and conform.nvim | ale 2026-10-20 (now dense-analysis/ale) |
| vim-php-refactoring-toolbox | Code actions | 2022-10-01 |
| vim-php-namespace | The code action “use App\Foo” | 2026-01-22 |
| vim-php-manual | K hover | 2020-12-09 |
| vim-project | Not in my config | 2021-08-27 |
| fzf and fzf.vim | snacks.nvim picker | fzf.vim 2026-09-30 |
A recent push date means that 2017 project is still maintained, even where I switched to newer tools.
Where should you start?
Build your Neovim PHP setup one layer at a time instead of pasting a dozen plugins into init.lua at once, so you can verify each piece in isolation. Installing a language server, completion, and Treesitter already covers daily PHP editing before you add save-time linters or formatters.
Recommended build order:
- Enable one PHP language server: choose PHPantom or tuned Phpactor for free rename and code actions, or Intelephense if you have the Premium licence. Verify it with
:checkhealth vim.lsp. - Add blink.cmp and LuaSnip for the completion menu, signature help, and PHP snippets.
- Configure nvim-treesitter for
phpandphpdocsyntax highlighting and indentation. - Layer on nvim-lint and conform.nvim once a project enforces custom
phpstan.neonor.php-cs-fixer.dist.phprules. Optional extras include Glance navigation, test coverage signs, and live refactoring previews.
If you want the raw benchmark data and tuning runs behind the language server recommendations, read the two appendices below, or scroll to the bottom to leave a comment.
Appendix: How did I measure and tune Phpactor?
All Intelephense and Phpactor benchmarks ran on a ThinkPad X9-15 Gen 1 (Intel Core Ultra 7, Ubuntu 24.04.5 LTS, PHP 8.3.6, Node.js v24.22.1, Neovim v0.13.0-dev). Each cell ran in 15 interleaved headless rounds. Lowering language_server.diagnostic_sleep_time to 100 ms was the only tuning change that gave a measurable gain.
You don’t need to read this section to set up Phpactor, because the Phpactor tuning section already includes that change. Every cell ran once per round after a discarded warm-up round, so machine load hit all cells alike. Earlier sequential batches shifted Phpactor’s startup by a factor of two, so I discarded them.
Neovim started the server fresh for every run and polled every 2 ms until the first definition answer. “Warm cache” reused the index cache from an earlier run. “Empty cache” deleted Intelephense’s storage folder or Phpactor’s XDG cache, data, and config folders first. The OS file cache stayed warm.
All Phpactor numbers use PHP 8.3.6 with its default CLI settings: OPcache off, JIT off, and Xdebug not loaded, except where a row names a setting. Phpactor ran as the release-page PHAR rather than through Mason, unless noted.
How do you make Phpactor index faster?
Phpactor’s default multi-worker indexing already saturates an 8-core CPU on a 2,817-file PHP application (6.3 s cold, 915 MB RAM). Enabling CLI OPcache, JIT, or test exclusions gives no gain. Setting indexer.parallel_workers to 1 slows cold indexing to 14.7 s while cutting RAM to 192 MB.
Each number in the table below is the median of 5 runs on that 2,817-file legacy application (no vendor folder), with the fastest and slowest run in brackets. The clock stops when the server reports that indexing has finished, and peak memory sums all server processes:
| Setup | Cold index | Warm index | Peak memory, cold |
|---|---|---|---|
| Intelephense | 2.0 s (1.8 to 2.5) | 0.4 s | 574 MB |
| Phpactor, default (8 workers) | 6.3 s (5.9 to 7.0) | 0.2 s | 915 MB |
| Phpactor, 1 worker | 14.7 s (14.6 to 15.1) | 0.2 s | 192 MB |
| Phpactor, 4 workers | 7.3 s (7.0 to 7.5) | 0.2 s | 605 MB |
| Phpactor, 16 workers | 6.0 s (5.9 to 6.2) | 0.3 s | 1,366 MB |
| Phpactor, OPcache with file cache | 6.4 s (5.6 to 6.8) | 0.2 s | 892 MB |
| Phpactor, OPcache and JIT | 6.4 s (6.3 to 6.9) | 0.2 s | 898 MB |
| Phpactor, tests excluded | 5.9 s (5.8 to 6.2) | 0.2 s | 911 MB |
Phpactor indexes with a pool of worker processes. indexer.parallel_workers defaults to 0, which started 8 index:worker processes on my 8-core CPU. One worker needs 14.7 s, four need 7.3 s, eight need 6.3 s, and sixteen need 6.0 s. More workers than cores waste memory, while 1 worker drops RAM from 915 MB to 192 MB.
OPcache and JIT changed nothing for indexing. My first test passed them as php -d flags, which never reach the worker processes. I repeated the test with an ini overlay (PHP_INI_SCAN_DIR) for every PHP process, and cold indexing stayed at 6.4 s.
Excluding the 303 test files with indexer.exclude_patterns gave 5.9 s (5.8 to 6.2) against 6.3 s (5.9 to 7.0). Because the ranges overlap and the exclusion costs you navigation in your tests, I would not configure an exclude pattern.
In the 5-run indexing table above, Intelephense finishes the cold index in 2.0 s against Phpactor’s 6.3 s and uses 574 MB against 915 MB. With a warm cache Phpactor is quicker: 0.2 s against 0.4 s. You pay the cold wait once per project.
How do you make Phpactor report errors faster?
Phpactor waits one second before it analyses a file again, and that delay is almost all of its 1.1 s to the first diagnostic. The option is language_server.diagnostic_sleep_time, in milliseconds, and its default is 1000. I timed lower values on the 7-file project with a warm cache across 10 runs.
diagnostic_sleep_time | Median first diagnostic | Range (fastest to slowest) |
|---|---|---|
| 1000 (default) | 1,115 ms | 1,106 to 1,155 ms |
| 500 | 601 ms | 595 to 616 ms |
| 250 | 500 ms | 422 to 547 ms |
| 100 | 299 ms | 285 to 435 ms |
| 0 | 330 ms | 312 to 478 ms |
| 0, diagnostics in the main process | 85 ms | 74 to 107 ms |
Below 100 ms nothing improves, because Phpactor runs the diagnostics in a separate process (language_server.diagnostic_outsource, on by default), and starting that process costs 250 to 300 ms. PHP settings do not change this, as the next section shows. Running the diagnostics in the main process reaches 85 ms on small files, but I do not recommend it: I timed only the opening of a file, not typing, and on every edit the main process would carry that work.
On the largest file of the legacy application (3.6 MB, 23,652 lines, median of 3 runs), the default needed 1,313 ms for the first diagnostic (1,293 to 1,695), while a sleep time of 100 needed 393 ms (387 to 397). Diagnostics in the main process needed 335 ms (328 to 337), only 58 ms less. A highlight request fired 100 ms after opening took 210 ms instead of 232 ms, so the lower delay did not hurt responsiveness; the Phpactor tuning section uses 100.
With nvim-lspconfig and the PHAR on PATH, opening a broken PHP file to the first diagnostic took 342 ms (332 to 348, median of 7 runs, warm cache) with the tuned config, against 1,255 ms (1,239 to 1,265) by default. Through Mason on a 2-file PHP project, the 7-run medians were 344 ms (332 to 354) and 1,247 ms (1,228 to 1,265).
A shorter delay lets Phpactor analyse more often while you type, because language_server.diagnostics_on_update is on by default. I did not measure that CPU cost; a sleep time of 250 is a middle ground if you want fewer runs.
Two more settings are left out in the config. language_server_highlight.enabled, which the docs call expensive on large documents, costs 11 ms per request on the 23,652-line file (9 to 19 ms), so there is nothing to save. indexer.reference_finder.deep and indexer.implementation_finder.deep changed the references time by 32 ms (637 ms against 669 ms), and they cut the implementations of the most extended type from 174 results to 127. The option description says they recurse over class implementations, so the 47 missing results should be indirect ones and I left both on.
The integrations for phpstan, php-cs-fixer, psalm, mago, and phpcs are off by default in this version (language_server_phpstan.enabled etc. are false), so Phpactor does not run phpstan a second time next to nvim-lint.
Do OPcache and JIT help Phpactor?
Enabling CLI OPcache (opcache.enable_cli=1), the OPcache file cache, or PHP 8.3 JIT gives no measurable gain for Phpactor. Across 15 interleaved rounds with an ini overlay applied to all worker and diagnostic child processes, warm definitions and diagnostics matched default PHP CLI settings within the spread.
I verified with opcache_get_status() that OPcache was active inside child processes receiving the PHP_INI_SCAN_DIR overlay:
| PHP setting | First definition, warm cache | First definition, empty cache | First diagnostic |
|---|---|---|---|
| Default (OPcache off, JIT off) | 132 ms (121 to 153) | 2.4 s (2.4 to 2.7) | 1.12 s (1.10 to 1.13) |
opcache.enable_cli=1 | 125 ms (121 to 199) | 2.5 s (2.4 to 3.2) | 1.12 s (1.10 to 1.14) |
The two rows match within the spread. My first sequential test claimed OPcache halved the warm start (263 ms against 135 ms). Default runs in that batch drifted between 132 and 263 ms, and the gap vanished once I interleaved the runs.
File cache and JIT matched plain OPcache in that first set. The OPcache file cache cannot help a PHAR anyway: it caches only the PHAR stub and none of the inner scripts. With the tuned config (diagnostic_sleep_time: 100), the first diagnostic stayed between 288 and 302 ms under every PHP setting. On the 3.6 MB legacy file, OPcache plus JIT gave 379 ms against 393 ms without them (3-run medians, overlapping ranges).
I also ran the whole flow, opening a file and waiting for the first diagnostic with the tuned config from the Phpactor section (median of 10 runs). It took 336 ms by default, 334 ms with php -d opcache.enable_cli=1 in front of the PHAR, and 331 ms with the setting in an ini file for every PHP process. So I left OPcache out of the recommended config.
Appendix: How did I measure PHPantom?
I benchmarked PHPantom 0.11.1 on the same ThinkPad X9-15 Gen 1 across 15 fresh headless Neovim runs on the 7-file PHP project and 6 runs on the 2,817-file legacy codebase. PHPantom reached workspace readiness in 0.65 s using 286 MB of RAM while writing zero cache files to disk.
Each timing below is the median of 15 runs after discarding the first warm-up round, with a fresh server per run and 2 ms polling until the first non-empty definition answer. Diagnostic timing ran from attaching a broken PHP file to the first buffer diagnostic, testing both immediately after the first answer and after a 3 s wait:
| Measure | Median | Range (fastest to slowest) |
|---|---|---|
Server ready (initialize answered) | 53 ms | 36 to 64 ms |
| First definition answer | 187 ms | 171 to 221 ms |
| First diagnostic, right after the first answer | 973 ms | 9 to 987 ms |
| First diagnostic, after 3 s | 506 ms | 505 to 509 ms |
One of the 15 runs read 9 ms for the first diagnostic right after the first answer, for reasons I did not track down, whereas after a 3 s wait every run landed near 506 ms, which looks like a fixed internal delay. Starting PHPantom with empty XDG cache, data, and config folders wrote zero files to disk.
The capability count (23) counts keys ending in Provider in Neovim’s client capabilities, which gives 15 for current Phpactor. Sending textDocument/prepareTypeHierarchy and textDocument/declaration manually returned the class Impl for the first and Method not found for the second.
For the big-project test, I copied the 2,817 PHP files and composer.json of the legacy application into an empty folder without .git or vendor and disabled phpstan and php-cs-fixer in PHPantom’s config to isolate indexing. The clock stopped at the progress message Parsed 2816 files (one file fewer than the folder holds), and peak memory came from VmHWM of the single server process 4 s after the first answer across 6 runs:
| Measure | Median | Range (fastest to slowest) |
|---|---|---|
| Workspace index ready | 0.65 s | 0.60 to 0.72 s |
| First definition answer | 0.24 s | 0.22 to 0.28 s |
Peak memory (VmHWM) | 286 MB | 279 to 307 MB |
The Intelephense and Phpactor numbers for the same files come from the indexing table, measured on an earlier day on the same machine. They are not from the same run, and the stop events differ: PHPantom’s clock runs until its own parse message, and the other two clocks run until the server reports that indexing has finished. PHPantom reads all files again on every start, which is why it has no separate warm number.
Questions, or a better setup? Leave a comment below.
















