Tooling
phaenon.json
Every key of phaenon.json, its default and an example, and how composer.json, .gitignore, PHPUnit, PHPStan and php-cs-fixer point at the outputs.
phaenon.json, at the root of a Composer project, tells phn which directories hold .phn
sources and where each one compiles to. Every command that works on a project reads it from the
working directory: phn build, phn check, phn fmt, phn fix, phn watch and the language
server.
{"roots": {"src": ".src", "tests": ".tests"}}This is the whole file for most projects: src/ compiles into .src/, tests/ into .tests/,
and the PHP target comes from composer.json.
The keys
| Key | Value | Default | Read since |
|---|---|---|---|
roots | Source directory → output directory | None: build, check and fmt without paths need it | 0.1.0 |
php | The PHP target, "8.5" or "8.6" | The lowest version composer.json's require.php admits, else 8.5 | 0.1.0 |
exclude | Paths the checker leaves alone | [] | 0.1.0 |
fmt | The command of phn fmt's second layer | The project's php-cs-fixer, if there is one | 0.2.0 |
unused | {"reflectedAttributes": [...]}: the attributes that spare a private property the dead-code warnings | Any attribute but PHP's own | 0.2.0 |
committed | Roots whose outputs the repository tracks | [] | 0.5.0 |
A project file that uses every key:
{
"roots": {"src": ".src", "tests": ".tests"},
"php": "8.6",
"exclude": ["tests/Fixture"],
"fmt": ["tools/php-cs-fixer/vendor/bin/php-cs-fixer", "fix"],
"unused": {"reflectedAttributes": ["Doctrine\\ORM\\Mapping\\MappingAttribute"]},
"committed": ["src"]
}Roots and their outputs
Each key of roots is a source directory and its value the directory it compiles into, a
sibling with the same parent: src → .src, tests → .tests, lib/src → lib/.src. The
output keeps the source's structure, so src/Domain/Order.phn compiles to
.src/Domain/Order.php.
The output sits at the same depth as its source so that __DIR__ does too. A compiled file runs
from .src/Kernel.php, and a path written against the source,
__DIR__ . '/../config/services.yaml' or dirname(__DIR__, 2), resolves to the same place from
there. For the same reason every file under a root that is not a .phn (a fixture, a YAML file, a
hand-written .php) is copied into the output, and an output whose source is gone is removed when
the whole project builds, so a deleted class does not linger.
phn refuses an output that is not a sibling, a root that compiles into itself, and roots that
overlap:
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 notphaenon.json: the output of "src" must be another directoryA root that the tree does not have is skipped, not refused. A production image that leaves
tests/ out of its build context builds src/ alone with the same phaenon.json.
The PHP target
The target is the oldest PHP the compiled code must run on: 8.5 or 8.6. Every 8.6 construct
parses whatever the target; the target decides what the output may contain. phn takes it from
"php", else from the lowest version composer.json's require.php admits (^8.5, >=8.5 and
8.5.* all mean 8.5), else it compiles for 8.5 and warns:
phaenon.json:1:1: warning P4010: no PHP target: neither phaenon.json's "php" nor composer.json's require.php states one; compiling for PHP 8.5For an 8.5 target, what PHP 8.6 added is lowered to 8.5 code where the lowering is exact. A partial application becomes an arrow function:
namespace App;
function euros(list<int> $cents): list<int> => array_map(intdiv(?, 100), $cents);<?php
/* @generated by phaenon from Example.phn */
declare(strict_types=1);
namespace App;
/**
* @param list<int> $cents
* @return list<int>
*/
function euros(array $cents): array
{
return array_map(fn(int $num1) => intdiv($num1, 100), $cents);
}With "php": "8.6" the same source keeps PHP 8.6's syntax:
namespace App;
function euros(list<int> $cents): list<int> => array_map(intdiv(?, 100), $cents);<?php
/* @generated by phaenon from Example.phn */
declare(strict_types=1);
namespace App;
/**
* @param list<int> $cents
* @return list<int>
*/
function euros(array $cents): array
{
return array_map(intdiv(?, 100), $cents);
}What has no exact lowering is an error under an 8.5 target, and so is a function, class or constant that PHP 8.6 added:
namespace App;
function capped(int $percent): int => clamp($percent, 0, 100);src/Example.phn:3:39: error P4011:
3 | function capped(int $percent): int => clamp($percent, 0, 100);
| ^^^^^
1 files checked: 1 errors, 0 warningsA target above what composer.json admits is warning P4008, since an install on the older PHP
would load code it cannot run: raise require.php (phn never edits composer.json). A target
phn does not compile for is error P4009, and phn build writes nothing:
phaenon.json:1:35: error P4009: PHP 8.4 is not a target phn compiles for: targets are 8.5 to 8.6
phn build: nothing compiled: the target is not one phn compiles forphn knows php-src's functions and classes for every target. It asks the local php for the
other extensions it has loaded (ext-mongodb, ext-redis), so that php should be as new as the
target. An 8.5 php under an 8.6 target gives a warning:
src/Example.phn:1:1: warning P4012: php is PHP 8.5.12, older than the target 8.6: the extensions it loads are known as they are on PHP 8.5 (PHN_PHP names another php)PHN_PHP=/path/to/php8.6 points phn at another php. phn migrate --php 8.6 writes the target
into phaenon.json.
Excluded paths
exclude lists files and directories the checker leaves alone: fixtures written for another
analyser, a file a rule set rewrites. phn check skips them; phn build compiles them all the same
and does not report their findings, since the project runs them.
{"roots": {"src": ".src"}, "exclude": ["src/Fixture"]}--exclude PATH on the command line adds more for one run.
The fixer phn fmt runs
fmt names the command phn fmt runs through phn fix as its second layer. Without the key,
phn fmt looks for tools/php-cs-fixer/vendor/bin/php-cs-fixer and then
vendor/bin/php-cs-fixer, and runs fix. An empty list turns the second layer off:
{"roots": {"src": ".src", "tests": ".tests"}, "fmt": []}Unused private members
The checker reports a private method or constant nothing uses (P2406), and a private property
only written (P2407) or only read (P2408), as warnings. A property that carries an attribute
is left alone by default, any attribute but PHP's own, since a framework reaches such a property
through reflection (a Doctrine column, a serializer group). unused.reflectedAttributes narrows
that to the attribute classes you name, their subclasses and implementations included; [] lets
none spare a property:
{"roots": {"src": ".src"}, "unused": {"reflectedAttributes": ["Doctrine\\ORM\\Mapping\\MappingAttribute"]}}Committed outputs
committed lists the roots whose outputs the project's repository tracks, each of them a key of
roots. It is for a library published as plain PHP; an application leaves it out. See
Publishing a library.
How the file is read
The file is one JSON object in UTF-8. A key phn does not know is an error, which catches a
misspelt key; so are a known key in another letter case and a key written twice:
phaenon.json: unknown key "output" (this is phn 0.7.2; a newer release may know it)phaenon.json: the key "Roots" is written "roots"The message names the release that read the file: an editor may run another phn than the one
the project pins. In the phaenon.json of an installed package, a key phn does not know is
passed over instead, since the project that installed the package cannot change it.
Beside it in composer.json
Composer loads the outputs, so the autoload maps name the output directories:
{
"require": {
"php": "^8.5",
"phaenon/phn": "^0.5"
},
"autoload": {
"psr-4": {"App\\": ".src/"}
},
"autoload-dev": {
"psr-4": {"App\\Tests\\": ".tests/"}
},
"config": {
"allow-plugins": {"phaenon/phn": true}
}
}An application requires phaenon/phn under require, not require-dev, because a production
install (composer install --no-dev) is where its outputs are built. allow-plugins lets the
plugin run. It reads two settings under extra.phaenon:
| Setting | Effect |
|---|---|
"binary-url": "https://phaenon.dev/releases/{version}/{file}" | Downloads the binary from this mirror instead of the GitHub release, with the credentials of auth.json |
"build": false | The plugin no longer builds the project at the autoload dump; your workflow runs phn build |
A project's functions may live in a .phn file under a root and be loaded through a "files"
autoload entry that names its output, ".src/functions.php": the checker reads such an entry
from its source, src/functions.phn, so each function is declared once.
.gitignore
An application builds its outputs where it runs, so the repository holds the sources only:
/vendor/
/.src/
/.tests/Pointing the tools at the outputs
PHP's tools run on the compiled code: the outputs are what PHP loads. phn trace maps what they
report back to the .phn (Line maps and debugging).
PHPUnit runs the compiled tests and measures the compiled sources, in phpunit.xml.dist:
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="vendor/autoload.php"
cacheDirectory=".phpunit.cache">
<testsuites>
<testsuite name="shop">
<directory>.tests</directory>
</testsuite>
</testsuites>
<source>
<include>
<directory>.src</directory>
</include>
</source>
</phpunit>PHPStan analyses the outputs, in phpstan.neon, with treatPhpDocTypesAsCertain: false
(why):
parameters:
level: max
paths:
- .src
- .tests
treatPhpDocTypesAsCertain: falsephp-cs-fixer, in .php-cs-fixer.dist.php, looks at the outputs with a PER Coding Style set, the
layout the compiler writes:
<?php
$finder = PhpCsFixer\Finder::create()
->in([__DIR__ . '/.src', __DIR__ . '/.tests']);
return (new PhpCsFixer\Config())
->setRules([
'@PER-CS3x0' => true,
])
->setFinder($finder);Rector, run through phn fix, takes the outputs as its paths in rector.php:
<?php
use Rector\CodeQuality\Rector\If_\SimplifyIfReturnBoolRector;
use Rector\Config\RectorConfig;
return RectorConfig::configure()
->withPaths([__DIR__ . '/.src'])
->withRules([SimplifyIfReturnBoolRector::class]);