Tooling
Editors
The PhpStorm plugin, the VS Code extension, phn lsp in Neovim and other editors, and phn watch in a terminal: what each gives and how to set it up.
Every editor gets Phaenon's findings from the same place: phn lsp, the compiler's language
server, run from the project's own vendor/bin/phn, so the editor checks with the compiler the
project builds with. On top of that, the PhpStorm plugin makes .phn a PHP file to PhpStorm, and
the VS Code extension adds highlighting and commands. Any editor with an LSP client can use the
server, and a terminal can run phn watch.
PhpStorm
The plugin teaches PhpStorm that a .phn file is PHP code from its first byte, without the open
tag, and hides Phaenon's syntax from PhpStorm's parser. According to the plugin's README, a
.phn then gets PhpStorm's own PHP support: highlighting, completion, parameter info, navigation
and Find Usages across .phn and .php files, refactorings, PHP's inspections, and Reformat
Code. Phaenon's types reach it: a
list<User> is a User[] to completion, a class<User> names User behind :: and new.
With a phn at hand, the plugin also starts phn lsp, for two things only:
- the checker's findings, as you type, against the whole project with the open files as they are, and on save for the whole project, with their quick-fixes;
- build on save: after each save the outputs are written as
phn buildwrites them, a file with errors withheld. The status bar shows the last build.
Everything else (navigation, completion, formatting) stays PhpStorm's. And through the line map
(Line maps and debugging) the plugin opens a
position in compiled code (a stack trace in a console, a PHPUnit failure, a PHPStan finding) at
its .phn line, and debugs .phn files with Xdebug.
Installing the plugin
The plugin is on the JetBrains Marketplace. In PhpStorm, open Settings → Plugins → Marketplace, search for Phaenon, install it and restart; the Marketplace then brings the updates.
To install a particular release from disk instead:
- Download
phaenon-jetbrains-<version>.zipfrom the releases page. - In PhpStorm, Settings → Plugins → ⚙ → Install Plugin from Disk…, pick the zip, and restart.
It requires PhpStorm 2026.1.4 or newer, or another JetBrains IDE of that version with the PHP plugin. The language server part uses the LSP API of the commercial IDEs; in an IDE without it the plugin works without the server. In an IDE without the PHP plugin (IntelliJ IDEA Community, WebStorm) it falls back to a TextMate grammar and highlights only.
A project with a phaenon.json needs no IDE setup: the plugin excludes the output directories,
so every class resolves to its .phn and is indexed once.
Settings
Settings | Languages & Frameworks | Phaenon names the phn to run and turns build on save off.
Without a setting, the plugin runs $PHN_BINARY, else the project's vendor/bin/phn, else phn
on the PATH.
Reformat Code writes PhpStorm's PHP style with Phaenon's layout: it runs phn fmt --stdin,
the first layer of phn fmt, before and after PhpStorm's formatter,
on a whole-file reformat. A .phn is always indented with spaces.
Known limits
The plugin's README lists them in full; among them:
- PhpStorm holds Phaenon's types as it can: a
map<K, V>is aV[], its key type lost; a tuple is the union of its elements; the type arguments of your own generics are dropped, so$box->get()has the bound ofBox's type parameter.phn checkis the authority on types. - PhpStorm's exception analysis reads
@throwstags, notthrowsclauses, and its quick-fixes add@throwstags. - A refactoring that adds a statement to an expression body (
=> expr;), such as Introduce Variable on part of it, breaks the body: write it as a block first. - Rename of a
typealias is refused, and Find Usages does not know aliases. - The debugger's Frames list labels a compiled frame with the compiled file's name, and coverage in PhpStorm reports compiled lines.
- After a plugin update that changes how a
.phnparses, the plugin re-indexes the project's.phnonce; if "PSI and index do not match" still shows, File | Invalidate Caches clears it.
Visual Studio Code
VS Code has no PHP engine for .phn, so everything beyond highlighting comes from phn lsp. The
extension's README lists:
| Feature | What it gives |
|---|---|
| Diagnostics | The checker's codes and messages, with "declared here" as related information; the quick-fix that replaces tabs |
| Hover | The type in Phaenon's spelling (map<string, User>, class<T>, (int, string)) and the docblock |
| Go to definition | Into .phn, vendor .php and PHP's stubs |
| Outline | The file's declarations |
| Completion | Members, names in scope, classes with their use; after |>, the functions that take the left side |
| Signature help | The parameters of the call being typed |
| Format Document | The first layer of phn fmt |
| Build on save | The outputs written after each save, a file with errors withheld |
The highlighting is VS Code's PHP grammar plus Phaenon's syntax, with PHP's scope names, so a theme colours Phaenon as it colours PHP.
Installing the extension
The extension is not on the VS Code Marketplace or Open VSX yet. Each release is a .vsix on the
releases page:
code --install-extension phaenon-0.4.0.vsixor Extensions → … → Install from VSIX…. It works on VS Code 1.91 and later, needs VS Code's
built-in PHP language support (the vscode.php extension, for the grammar), and php on the
PATH, which the compiler asks for the extensions it has loaded.
The extension runs, in order: the phaenon.binary setting, $PHN_BINARY, the project's
vendor/bin/phn, then phn on the PATH. In an untrusted workspace it highlights only, since
the server and the commands run the project's vendor/bin/phn.
Settings, commands and tasks
| Setting | Default | |
|---|---|---|
phaenon.binary | empty | The phn to run |
phaenon.buildOnSave | true | Builds the project after each save |
phaenon.traceRoots | {} | For the trace commands: {"/app": "."} reads a trace from a container, as phn trace --root does |
phaenon.trace.server | off | Logs the messages with the server in the Phaenon output |
- Phaenon: Build the Project and Phaenon: Check the Project run
phn buildandphn checkas tasks. Thephaenontask type listsbuild,checkandwatchfor every project, also fortasks.json:{"type": "phaenon", "command": "watch"}. - Phaenon: Trace the Selection to .phn Positions runs
phn traceon the selection, or on the whole document; Trace the Terminal's Text on the terminal's selection or buffer. - Phaenon: Restart the Language Server, after a
composer installthat changed the compiler.
Each project gets its own server: a file belongs to the nearest phaenon.json above it, else the
nearest composer.json. A .phn under vendor/ is installed code and is highlighted only.
Debugging .phn is not there yet: VS Code's PHP debug adapter maps directories, not a file to one
with another extension. PhpStorm debugs .phn today.
Other editors: phn lsp
phn lsp speaks the Language Server Protocol on standard input and output. It serves the project
around its working directory, the nearest directory above it with a phaenon.json, else a
composer.json, so start it there. It answers diagnostics, hover, go to definition, document
symbols, completion, signature help and formatting, and builds the outputs after each save.
Two initialization options adjust it:
| Option | Effect |
|---|---|
buildOnSave | false turns the build on save off (default true) |
features | "diagnostics" makes it advertise diagnostics and their quick-fixes only, for an editor that answers the rest itself |
After a build on save it sends its own notification, phaenon/build, with the counts of files
written and withheld; a client may show it or ignore it.
Neovim
With Neovim 0.12's built-in client, in init.lua:
-- .phn files get a filetype of their own, so that no PHP language server attaches to them.
vim.filetype.add({ extension = { phn = 'phaenon' } })
vim.lsp.config('phn', {
filetypes = { 'phaenon' },
root_markers = { 'phaenon.json', 'composer.json' },
-- The project's own compiler, started in the project's directory: phn lsp serves the
-- project around its working directory.
cmd = function(dispatchers, config)
local phn = config.root_dir .. '/vendor/bin/phn'
if vim.fn.executable(phn) == 0 then
phn = 'phn'
end
return vim.lsp.rpc.start({ phn, 'lsp' }, dispatchers, { cwd = config.root_dir })
end,
})
vim.lsp.enable('phn')This configuration was run with Neovim 0.12.2, headless, on a project with the compiler installed
by Composer: the checker's findings arrived as diagnostics, hover answered with the type
($sum: int), vim.lsp.buf.format() laid out map< string,int > as map<string, int>, and a
save built the outputs, also when Neovim was started outside the project. Add
init_options = { buildOnSave = false } to turn the build on save off. It was not tried with
older releases of Neovim, and it gives no highlighting: the phaenon filetype has no syntax
of its own.
Any other client
Configure the command vendor/bin/phn lsp, run in the project's root, for files ending in
.phn. Keep other PHP language servers off those files: they would read Phaenon's syntax as
errors.
phn watch in a terminal
For an editor without an LSP client, or beside any editor, phn watch checks and builds the
project each time one of its files changes:
vendor/bin/phn watch5 files checked: 0 errors, 0 warnings
5 files compiled, 0 outputs written, 0 withheld (0.3s)
phn watch: waiting for changes (Ctrl-C to stop)
src/Discount.phn:8:16: error P2202: App\Discount::applies() should return bool but returns int
8 | return $cents;
| ^^^^^^
5 files checked: 1 errors, 0 warnings
5 files compiled, 0 outputs written, 1 withheld (0.0s)
phn watch: waiting for changes (Ctrl-C to stop)--no-build checks only. It reads phaenon.json and composer.json again when either changes.
Ctrl-C stops it.