ToolingLocal development

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 watch in a terminal, which checks and builds after each change.
  • vendor/bin/phn build (or composer build) by hand, or composer 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 trace

phn 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.xml

The 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 removed

vendor/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 error

and 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 error

vendor/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 roots

phaenon.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 not

Composer 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\TestCase

Leave 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.