ToolingThe phn command

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

CommandWhat it does
phn buildType-checks and compiles the roots into their output directories
phn checkType-checks and writes nothing
phn fmtLays the .phn out in Phaenon's layout, then runs the project's fixer
phn fixRuns php-cs-fixer or Rector on the outputs and carries their changes back into the .phn
phn traceRewrites positions in compiled files, in text or in a report, as .phn positions
phn watchChecks and builds each time a file of the project changes
phn lspThe language server an editor starts
phn migrateRewrites .php files as .phn
phn versionPrints 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
OptionEffect
--checkWrites nothing; fails when an output is missing, stale or has no source left
--emit-on-errorWrites the output of a file with type errors too; the exit status still reports them
--exclude PATHLeaves this path's findings unreported; repeatable
--out DIRWrites the outputs under DIR instead of beside the sources
--vendorCompiles 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 build
5 files compiled, 5 written, 0 files copied, 0 stale outputs removed

The 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.phn
1 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>...]
OptionEffect
--formattext (the default), json, github or checkstyle
--jsonThe same as --format=json
--no-deprecationsLeaves out the findings about what PHP deprecates
--exclude PATHSkips 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 check
src/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 warnings

In 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
OptionEffect
--checkWrites nothing; fails when either layer would change a file
--stdinLays 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 fmt
4 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 nothing

The 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>...]
OptionEffect
--checkReports 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 process
rector changed 1 files: 2 changes carried back to 1 sources, 0 in text the compiler wrote
after the rebuild, rector changes nothing

The 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>...]
OptionEffect
--root PREFIX=LOCALReads 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:14

On 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]
OptionEffect
--no-buildChecks only; writes no outputs
--intervalHow 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 lsp

The 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>...
OptionEffect
--keep-docblocksLeaves generic docblocks as they are
--keep-publicKeeps the public of a method lifted out of function, and before private(set)
--keep-layoutKeeps braces, docblocks and bodies as they are
--keep-callsKeeps nested calls as they are, with no pipelines
--pipes=NWrites chains of this many nested calls or more as pipelines (default 3)
--list-typesTypes bare array declarations as list<T> or map<K, V> where every value they hold says so
--php X.YWrites 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 src
phaenon.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 calls

A 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 version
phn 0.7.2

A 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; --php reads plain PHP with its open tag.
  • phn print [--php] <file> parses and pretty-prints.
  • phn stdlib --out DIR [--check] writes the PHP the phaenon/debug package ships.

Exit status

StatusMeaning
0Done; phn check found warnings at most
1An 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
2No command, an unknown command, or an unknown option
126vendor/bin/phn found the binary and could not run it
127vendor/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

VariableRead byEffect
PHN_BINARYvendor/bin/phn, the Composer plugin, the editor pluginsRuns this binary instead of the pinned one
PHN_PHPphnThe 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).