Toolingphaenon.json

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

KeyValueDefaultRead since
rootsSource directory → output directoryNone: build, check and fmt without paths need it0.1.0
phpThe PHP target, "8.5" or "8.6"The lowest version composer.json's require.php admits, else 8.50.1.0
excludePaths the checker leaves alone[]0.1.0
fmtThe command of phn fmt's second layerThe project's php-cs-fixer, if there is one0.2.0
unused{"reflectedAttributes": [...]}: the attributes that spare a private property the dead-code warningsAny attribute but PHP's own0.2.0
committedRoots 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 not
phaenon.json: the output of "src" must be another directory

A 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.5

For 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:

you write
namespace App;

function euros(list<int> $cents): list<int> => array_map(intdiv(?, 100), $cents);
phn build writes
<?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:

you write
namespace App;

function euros(list<int> $cents): list<int> => array_map(intdiv(?, 100), $cents);
phn build writes, for PHP 8.6
<?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:

you write
namespace App;

function capped(int $percent): int => clamp($percent, 0, 100);
$ phn checkexit 1
src/Example.phn:3:39: error P4011: clamp() needs PHP 8.6 (target 8.5)
    3 | function capped(int $percent): int => clamp($percent, 0, 100);
      |                                       ^^^^^
1 files checked: 1 errors, 0 warnings

A 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 for

phn 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": []}

See Formatting and fixers.

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:

SettingEffect
"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": falseThe 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: false

php-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]);