Tooling
The phn command
Every phn command a project runs, from build and check to fmt, fix, trace and watch, with its options, its exit status and an example.
phn is the Phaenon compiler: one static binary that type-checks .phn files, compiles them to
PHP, lays them out, and maps positions in the compiled PHP back to the source. In a Composer
project the phaenon/phn plugin installs the release composer.lock pins as vendor/bin/phn
(Install).
The examples on this page write vendor/bin/phn where they run in a project. Inside a Composer
script, vendor/bin is on the PATH, so a script runs phn build as it runs phpunit. Every
command that works on a project reads phaenon.json from the working directory, so run them from
the project's root (phaenon.json).
The commands
| Command | What it does |
|---|---|
phn build | Type-checks and compiles the roots into their output directories |
phn check | Type-checks and writes nothing |
phn fmt | Lays the .phn out in Phaenon's layout, then runs the project's fixer |
phn fix | Runs php-cs-fixer or Rector on the outputs and carries their changes back into the .phn |
phn trace | Rewrites positions in compiled files, in text or in a report, as .phn positions |
phn watch | Checks and builds each time a file of the project changes |
phn lsp | The language server an editor starts |
phn migrate | Rewrites .php files as .phn |
phn version | Prints the release |
phn without a command prints the usage on standard error and exits with status 2; phn help
(also -h, --help) prints it on standard output. phn <command> --help lists the command's
options. An option phn does not know ends the command with status 2 and the command's options.
phn build
phn build [--out DIR] [--check] [--emit-on-error] [--exclude PATH]... [<path>...]
phn build --vendor| Option | Effect |
|---|---|
--check | Writes nothing; fails when an output is missing, stale or has no source left |
--emit-on-error | Writes the output of a file with type errors too; the exit status still reports them |
--exclude PATH | Leaves this path's findings unreported; repeatable |
--out DIR | Writes the outputs under DIR instead of beside the sources |
--vendor | Compiles the installed Composer packages that carry a phaenon.json |
Without paths, phn build compiles the roots phaenon.json names. Each root compiles into its
output directory, every other file under the root is copied there, and an output whose source is
gone is removed:
vendor/bin/phn build5 files compiled, 5 written, 0 files copied, 0 stale outputs removedThe build checks first. A file with an error is not written, its findings go to standard error, and the command fails; the output a previous build wrote for that file stays as it was:
src/Receipt.phn:8:16: error P2202: App\Receipt::total() should return string but returns int
8 | return $sum;
| ^^^^
1 of 6 files failed to compile--emit-on-error writes such a file all the same, which is how a code base that is still fixing
its findings keeps running (The type checker).
With paths, phn build compiles those files, or the .phn under those directories. In a project
they go to their place in the output directory, but nothing is copied and nothing removed. Without
a phaenon.json, Foo.phn compiles to Foo.php beside it, or under --out DIR at the same
relative path:
phn build --out build OutOfStock.phn1 files compiled, 1 written--check compares instead of writing. Each output that differs is named on standard error:
.src/CurrencyMismatch.php: stale or missing
1 outputs are stale, 0 copies are stale, 0 outputs have no source; run `phn build`Combined with --emit-on-error, a file with errors passes when its output is what such a build
writes. --vendor takes no paths and no other option; it builds the installed packages as the
Composer plugin does at every autoload dump (Publishing a library).
The exit status is 0 when every file compiled, 1 when one failed, when --check finds a
difference, or when a library's composer.json lacks the conflict its phaenon.json asks for
(Publishing a library).
phn check
phn check [--format=F] [--no-deprecations] [--exclude PATH]... [<path>...]| Option | Effect |
|---|---|
--format | text (the default), json, github or checkstyle |
--json | The same as --format=json |
--no-deprecations | Leaves out the findings about what PHP deprecates |
--exclude PATH | Skips this path; repeatable |
Without paths it checks the roots of phaenon.json, minus its exclude list. A .php file under
a root is checked too, as PHP, unless a .phn of the same name stands beside it.
vendor/bin/phn checksrc/Example.phn:13:13: warning P2406: private method App\Basket::label() is never used
13 | private label(): string => 'basket';
| ^^^^^
src/Example.phn:16:46: error P2202: function App\checkout() should return string but returns int
16 | function checkout(Basket $basket): string => $basket->total();
| ^^^^^^^^^^^^^^^^
1 files checked: 1 errors, 1 warningsIn the text format the findings go to standard error and the summary to standard output. The exit status is 1 when there is an error and 0 otherwise, warnings included. The formats, the codes and what the checker reads are on The type checker.
phn fmt
phn fmt [--check] [<path>...]
phn fmt --stdin| Option | Effect |
|---|---|
--check | Writes nothing; fails when either layer would change a file |
--stdin | Lays out standard input onto standard output, in Phaenon's layout alone |
phn fmt formats in two layers: Phaenon's layout, then the project's php-cs-fixer through
phn fix. Without paths it formats the roots; a directory stands for the .phn under it.
vendor/bin/phn fmt4 files formatted, 1 changed in Phaenon's layout
PHP CS Fixer 3.95.30 Adalbertus by Fabien Potencier, Dariusz Ruminski and contributors.
…
php-cs-fixer changed 1 files: 3 changes carried back to 1 sources, 0 in text the compiler wrote
after the rebuild, php-cs-fixer changes nothingThe exit status is 1 when --check finds a change, when a file does not parse (the others are
formatted), or when the fixer still changes something; when the fixer itself fails, phn fmt
exits with the fixer's status. --stdin takes no paths and exits with 0 unless the input does
not parse. The layers are described on Formatting and fixers.
phn fix
phn fix [--check] -- <command> [<arg>...]| Option | Effect |
|---|---|
--check | Reports every change the tool makes at its .phn line, and writes no source |
phn fix builds the project, runs the command on the outputs, carries the changes the tool made
back into the .phn, rebuilds, and runs the tool again until nothing more is carried (three rounds
at most):
vendor/bin/phn fix -- vendor/bin/rector processrector changed 1 files: 2 changes carried back to 1 sources, 0 in text the compiler wrote
after the rebuild, rector changes nothingThe exit status is the tool's when the tool fails, 1 when changes are left (with --check, when
there is any change), and 0 otherwise. It needs a phaenon.json with roots. What is carried and
what is not is on Formatting and fixers.
phn trace
phn trace [--root PREFIX=LOCAL]... [<text>...]| Option | Effect |
|---|---|
--root PREFIX=LOCAL | Reads a path under PREFIX from LOCAL; repeatable |
phn trace rewrites positions in compiled files as .phn positions: file.php:42,
file.php(42) and file.php on line 42, wherever the file ends with a line map. Everything else
passes through unchanged. It reads its arguments, joined by spaces, or standard input without
them:
vendor/bin/phn trace ".src/Inventory.php:28"src/Inventory.phn:14On standard input it also reads GitHub workflow commands, and Checkstyle, JUnit, Clover and Cobertura reports, which it writes back as the same report. It exits with 0. Its uses are on Line maps and debugging.
phn watch
phn watch [--no-build] [--interval D]| Option | Effect |
|---|---|
--no-build | Checks only; writes no outputs |
--interval | How often to look for changes (default 300ms) |
phn watch checks and builds the project around the working directory at start, then each time
one of its files changes, until you stop it with Ctrl-C. It takes no paths: it watches the roots.
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)See Local development.
phn lsp
phn lspThe language server of the project around the working directory, speaking the Language Server
Protocol on standard input and output. Editors start it; --stdio is accepted and is the only
transport. It moves to the nearest directory above the working directory that holds a
phaenon.json, else a composer.json, and serves that project. See Editors.
phn migrate
phn migrate [--keep-docblocks] [--keep-public] [--keep-layout] [--keep-calls] [--pipes=N] [--list-types] [--php X.Y] <path>...| Option | Effect |
|---|---|
--keep-docblocks | Leaves generic docblocks as they are |
--keep-public | Keeps the public of a method lifted out of function, and before private(set) |
--keep-layout | Keeps braces, docblocks and bodies as they are |
--keep-calls | Keeps nested calls as they are, with no pipelines |
--pipes=N | Writes chains of this many nested calls or more as pipelines (default 3) |
--list-types | Types bare array declarations as list<T> or map<K, V> where every value they hold says so |
--php X.Y | Writes this target into phaenon.json, creating the file if needed |
phn migrate rewrites Foo.php as Foo.phn and removes the .php. It also runs on .phn
files, to lift what an earlier run left.
phn migrate --php 8.5 srcphaenon.json: target PHP 8.5
1 files migrated, 0 skipped, 0 .phn files updated, 0 docblock tags kept
1 @throws lifted, 1 bodies written as =>, 1 braces moved up, 0 class braces moved down, 0 empty bodies written as {}, 0 docblocks collapsed; 34 lines became 15
0 chains as pipelines, 0 left as callsA phaenon.json that --php creates states only the target; add the roots before you build.
The walk through a whole project is Migrate a PHP project.
phn version and phn help
vendor/bin/phn versionphn 0.7.2A binary built from source calls itself dev. phn help prints the usage.
For the compiler's own development
phn lex [--php] <file>prints the token stream;--phpreads plain PHP with its open tag.phn print [--php] <file>parses and pretty-prints.phn stdlib --out DIR [--check]writes the PHP thephaenon/debugpackage ships.
Exit status
| Status | Meaning |
|---|---|
| 0 | Done; phn check found warnings at most |
| 1 | An error: a finding of severity error, a file that did not compile, a stale output under --check, a change left by fmt or fix, or a problem with phaenon.json |
| 2 | No command, an unknown command, or an unknown option |
| 126 | vendor/bin/phn found the binary and could not run it |
| 127 | vendor/bin/phn has no binary and could not fetch one |
phn fmt and phn fix pass on the status of a fixer that fails.
Environment variables
| Variable | Read by | Effect |
|---|---|---|
PHN_BINARY | vendor/bin/phn, the Composer plugin, the editor plugins | Runs this binary instead of the pinned one |
PHN_PHP | phn | The php that phn asks for the extensions it has loaded (default: php on the PATH) |
phn reads the extensions beyond php-src's from a local php, which should be as new as the
target: for an 8.6 target an 8.5 php gives warning P4012 (phaenon.json).