ToolingEditors

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 build writes 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:

  1. Download phaenon-jetbrains-<version>.zip from the releases page.
  2. 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 a V[], 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 of Box's type parameter. phn check is the authority on types.
  • PhpStorm's exception analysis reads @throws tags, not throws clauses, and its quick-fixes add @throws tags.
  • 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 type alias 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 .phn parses, the plugin re-indexes the project's .phn once; 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:

FeatureWhat it gives
DiagnosticsThe checker's codes and messages, with "declared here" as related information; the quick-fix that replaces tabs
HoverThe type in Phaenon's spelling (map<string, User>, class<T>, (int, string)) and the docblock
Go to definitionInto .phn, vendor .php and PHP's stubs
OutlineThe file's declarations
CompletionMembers, names in scope, classes with their use; after |>, the functions that take the left side
Signature helpThe parameters of the call being typed
Format DocumentThe first layer of phn fmt
Build on saveThe 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.vsix

or 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

SettingDefault
phaenon.binaryemptyThe phn to run
phaenon.buildOnSavetrueBuilds 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.serveroffLogs the messages with the server in the Phaenon output
  • Phaenon: Build the Project and Phaenon: Check the Project run phn build and phn check as tasks. The phaenon task type lists build, check and watch for every project, also for tasks.json: {"type": "phaenon", "command": "watch"}.
  • Phaenon: Trace the Selection to .phn Positions runs phn trace on 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 install that 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:

OptionEffect
buildOnSavefalse 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 watch
5 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.