Tooling
Local development
The day-to-day loop on a Phaenon project: building as you work, running a test and reading its failure on .phn lines, Docker, and the common mistakes.
Working on a Phaenon project is working on a PHP project whose PHP is built from the .phn you
edit. The loop has one extra step, the build, and editors run it for you on save. This page
follows that loop on a project set up as in A first project.
The project on your machine
composer install brings the compiler as vendor/bin/phn and builds every root, so a fresh
clone runs as soon as the install is done. Your editor checks as you type and builds on save
(Editors). The outputs, .src/ and .tests/, are what PHP, PHPUnit and
PHPStan run; you never edit them.
Composer scripts put vendor/bin on the PATH, so a project can name its commands once:
{
"scripts": {
"build": "phn build",
"cs": "phn fmt",
"cs:check": "phn fmt --check",
"test": "phpunit"
}
}Building as you work
A test runs the outputs, so a change reaches it once the project is built. Any of these builds:
- The editor's build on save: PhpStorm, VS Code and an LSP client such as Neovim write the outputs after each save, a file with errors withheld.
vendor/bin/phn watchin a terminal, which checks and builds after each change.vendor/bin/phn build(orcomposer build) by hand, orcomposer dump-autoload, which runs the plugin's build.
A file with an error is not written, so the previous output of that file keeps running until the
error is fixed. phn watch and the build on save say so: 1 withheld.
Running a test
Run PHPUnit as in any project; its configuration points at .tests and .src
(phaenon.json):
vendor/bin/phpunit --filter testRefusesMoreThanThere…
OK (1 test, 1 assertion)A failure reports positions in the compiled files. Pipe the output through phn trace to read it
on the .phn lines:
vendor/bin/phpunit 2>&1 | vendor/bin/phn trace…
1) App\Tests\RestockTest::testTakesAfterRestocking
App\OutOfStock: pear: 2 wanted, 1 left
/app/src/Inventory.phn:14
/app/tests/RestockTest.phn:11
…PhpStorm with the Phaenon plugin needs no pipe: its test runner and consoles link a compiled
position to its .phn line, and its debugger stops at breakpoints set in the .phn
(Line maps and debugging). In VS Code, Phaenon:
Trace the Terminal's Text does what the pipe does.
PHPStan and coverage
PHPStan analyses the outputs; its findings go through phn trace too:
vendor/bin/phpstan analyse --no-progress --error-format=raw | vendor/bin/phn tracephn check already reports what PHPStan reports at level max, so PHPStan earns its place through
its extensions and your project's own rules (The type checker).
For coverage, PCOV must be told to measure the outputs, or it measures src/ and reports nothing:
php -d pcov.directory=. vendor/bin/phpunit --coverage-clover clover.xml
vendor/bin/phn trace < clover.xml > clover.phn.xmlThe traced report counts .phn lines, for an IDE or a coverage service to read.
After git pull
Run composer install. It installs what composer.lock changed, and it always writes the
autoloader, so the plugin builds the project: new sources are compiled, and the outputs of
sources that are gone are removed.
Installing dependencies from lock file (including require-dev)
Verifying lock file contents can be installed on current platform.
Nothing to install, update or remove
Generating autoload files
> phn build
5 files compiled, 0 written, 0 files copied, 0 stale outputs removedvendor/bin/phn build does the same when the lock did not change. The outputs are never
committed in an application, so a pull never conflicts on them.
Working in Docker
The plugin downloads the phn binary for the platform Composer runs on: on a Mac, a macOS
binary; in a Linux container, a Linux one, for the container's architecture. It installs it in
vendor/phaenon/phn/bin/, so the platform that last ran composer install or composer dump-autoload owns the binary.
When the project directory, vendor/ included, is mounted into a container, the two sides take
the binary from each other. A macOS binary run in the container fails with an exec format error,
whose wording depends on the container runtime; one prints:
Cannot run macOS (Mach-O) executable in Docker: Exec format errorand after a composer install in the container, the Linux binary fails on the Mac:
phaenon/phn: cannot run …/vendor/phaenon/phn/bin/phn: Exec format errorvendor/bin/phn exits with 126 in both cases. A composer dump-autoload on the side you are on
puts that side's binary back, from Composer's cache. To stop the back and forth, run Composer and
phn on one side only, or keep the container's vendor/ in a volume of its own.
A trace from the container names its paths, /app/.src/Inventory.php(28); phn trace --root /app=. reads them from your checkout. VS Code's phaenon.traceRoots setting does the same for
its trace commands.
Common mistakes
A change does not show in the test. The .phn was saved but not built: the editor's build on
save is off, or the file has an error and its output was withheld. Run vendor/bin/phn build and
read its findings.
An edit to .src/ disappears. The outputs are rewritten from the sources at every build. Edit
the .phn. phn build --check names an output that differs from what the build writes:
.src/CurrencyMismatch.php: stale or missing
1 outputs are stale, 0 copies are stale, 0 outputs have no source; run `phn build`Class "App\Inventory" not found. Composer's autoload points at src/, where PHP finds no
.php; it names the outputs, "App\\": ".src/".
PHPStan finds nothing to analyse. Its paths name src:
[ERROR] No files found to analyse.Point them at .src and .tests.
phn build asks for paths. There is no phaenon.json, or it names no roots:
phn build: give paths, or a phaenon.json naming the rootsphaenon.json is refused. The message says why, a key misspelt or an output that is not a
sibling of its root (How the file is read):
phaenon.json: the output of "src" must be its sibling, a directory with the same parent, so that __DIR__ keeps its depth; "build/src" is notComposer blocks the plugin. Composer runs only the plugins allow-plugins names, and
without the entry it stops:
phaenon/phn contains a Composer plugin which is blocked by your allow-plugins config. You may add it to the list if you consider it safe.Add "allow-plugins": {"phaenon/phn": true} under config.
composer install --no-dev fails on the tests. The plugin builds every root the tree has, and
without the development dependencies tests/ cannot compile:
tests/InventoryTest.phn:7:35: error P2001: unknown class PHPUnit\Framework\TestCaseLeave tests/ out of a production tree, as a .dockerignore does
(Continuous integration).
Coverage is 0 everywhere. PCOV measures src/ by default; run PHPUnit with
-d pcov.directory=..
A finding names a line that does not match the file. It is a compiled line. Pass the text
through phn trace, or open the position from PhpStorm, which maps it.