Tooling
Publishing a library
Publishing a Composer library written in Phaenon so that composer require brings plain PHP, committing its outputs and keeping them current.
A library written in Phaenon can be published so that composer require brings plain PHP: any
project installs it, with or without Phaenon, and nothing in it calls a Phaenon package. The
library commits its compiled outputs beside its .phn and names them in phaenon.json; its CI
checks that they are what its sources compile to.
Two ways to publish
Outputs committed ("committed") | Sources only | |
|---|---|---|
| The repository holds | src/*.phn and .src/*.php | src/*.phn |
| A project without Phaenon gets | The compiled PHP, ready to load | Nothing it can load without the plugin |
| A project written in Phaenon gets | The compiled PHP, and the checker reads the .phn | Its plugin builds the library at every autoload dump |
phaenon/phn in the library's composer.json | require-dev, one exact release | require, a range |
Shipping sources only suits a library whose consumers are Phaenon projects already. A library for PHP projects at large commits its outputs; the rest of this page is about that way.
The repository
acme/money
├── src/Money.phn
├── src/CurrencyMismatch.phn
├── .src/Money.php # compiled, committed
├── .src/CurrencyMismatch.php
├── tests/MoneyTest.phn
├── phaenon.json
├── composer.json
├── .gitattributes
└── .gitignorenamespace Acme\Money;
final readonly class Money
{
__construct(public int $cents, public string $currency) {}
/** The total of the amounts, null for none. */
static sum(list<Money> $amounts): ?Money throws CurrencyMismatch {
$total = null;
foreach ($amounts as $amount) {
$total = $total === null ? $amount : $total->plus($amount);
}
return $total;
}
plus(Money $other): Money throws CurrencyMismatch {
if ($other->currency !== $this->currency) {
throw new CurrencyMismatch($this->currency, $other->currency);
}
return new Money($this->cents + $other->cents, $this->currency);
}
/** The amount as stored: eight bytes, big-endian. */
pack(): bytes => (bytes) pack('J', $this->cents);
}<?php
/* @generated by phaenon from Money.phn */
declare(strict_types=1);
namespace Acme\Money;
final readonly class Money
{
public function __construct(public int $cents, public string $currency) {}
/**
* The total of the amounts, null for none.
* @param list<Money> $amounts
* @throws CurrencyMismatch
*/
public static function sum(array $amounts): ?Money
{
$total = null;
foreach ($amounts as $amount) {
$total = $total === null ? $amount : $total->plus($amount);
}
return $total;
}
/**
* @throws CurrencyMismatch
*/
public function plus(Money $other): Money
{
if ($other->currency !== $this->currency) {
throw new CurrencyMismatch($this->currency, $other->currency);
}
return new Money($this->cents + $other->cents, $this->currency);
}
/** The amount as stored: eight bytes, big-endian. */
public function pack(): string
{
return pack('J', $this->cents);
}
}namespace Acme\Money;
final class CurrencyMismatch extends \DomainException
{
__construct(string $left, string $right) {
parent::__construct("$left and $right do not add up");
}
}phaenon.json lists the roots whose outputs the repository tracks. The tests are not among them:
consumers load the library, not its tests.
{"roots": {"src": ".src", "tests": ".tests"}, "committed": ["src"]}composer.json:
{
"name": "acme/money",
"description": "Amounts of money, written in Phaenon and published as PHP",
"type": "library",
"license": "MIT",
"require": {
"php": "^8.5"
},
"require-dev": {
"phaenon/phn": "0.7.2",
"phpunit/phpunit": "^12.5"
},
"conflict": {
"phaenon/phn": "<0.5.0"
},
"autoload": {
"psr-4": {
"Acme\\Money\\": ".src/"
}
},
"autoload-dev": {
"psr-4": {
"Acme\\Money\\Tests\\": ".tests/"
}
},
"config": {
"allow-plugins": {
"phaenon/phn": true
}
}
}- The compiler is a development requirement, at one exact release. The outputs are made before
publishing, so a consumer needs no compiler, and Composer installs no development requirement of
a dependency: no plugin, no binary, no
allow-pluginsquestion. The release is exact because two releases may write different bytes for the same source, and the committed bytes come from one compiler. - The
conflictkeeps out the compilers that cannot read the sources. It applies only wherephaenon/phnis installed beside the library, in a project written in Phaenon, whose checker reads the library's.phn. Its floor is never below 0.5.0, the first release that knowscommitted, andphn buildchecks it (below). - No
composer.lockis committed, as in any library. - Upgrading the compiler is one pull request: the new release in
require-dev, and the.src/it writes. The install that brings the release builds the project, so the two arrive together.
.gitignore tracks .src/, unlike an application's:
/vendor/
/.tests/
.phn-build
/composer.lock.phn-build is the stamp a build of an installed package leaves; listing it keeps one from being
committed by accident. .gitattributes marks the outputs as generated, so a pull request shows
them collapsed and the review is of the .phn, and keeps the tests out of the archive Packagist
serves:
/.src/** linguist-generated
/tests export-ignore
/.gitignore export-ignore
/.gitattributes export-ignoreThe archive of a release then holds what a consumer needs: the outputs that run, the .phn their
line maps name, and phaenon.json, through which a Phaenon consumer finds the sources:
git archive v1.0.0 | tar -t.src/
.src/CurrencyMismatch.php
.src/Money.php
composer.json
phaenon.json
src/
src/CurrencyMismatch.phn
src/Money.phnKeep .src/ out of any /.* export-ignore line: such a habit of PHP libraries would drop the
outputs from every release, and nothing run on a checkout would notice.
The gate
The CI job that installs the dependencies builds, and then asks git whether the committed outputs changed:
composer install --no-interaction --no-progress
vendor/bin/phn build
git diff --exit-code -- .src
test -z "$(git status --porcelain -- .src)"
git archive HEAD | tar -tphn buildtakes no paths and no--emit-on-error: it fails on a file with errors, and it mirrors the root, removing an output whose source is gone.- The two git commands come after every step that builds (
phn fmt --checkandphn fix --checkrebuild the outputs too). A stale output shows as modified, a missing one as untracked, an orphan as deleted. - The listing is there to read: it must show
phaenon.json,src/and.src/, and notests/.
A source edited without a build fails it; with --stat, the diff names the output that moved:
git diff --exit-code --stat -- .src .src/CurrencyMismatch.php | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)Make it a required check, merge branches up to date with the main branch, and tag releases only on commits that passed it: one file's output can depend on another file's declarations, so two pull requests that pass apart can leave the main branch stale together.
Locally, phn build --check asks the same question and writes nothing:
.src/CurrencyMismatch.php: stale or missing
1 outputs are stale, 0 copies are stale, 0 outputs have no source; run `phn build`The outputs also depend on the declarations of the library's dependencies, which the compiler reads for imports and generics, so a dependency's release can turn the gate red with no commit in the library. Rebuild and commit.
The conflict the build checks
In a project that commits a root, phn build (without paths) and phn build --check read the
conflict on phaenon/phn in composer.json, and fail while it lets in a release that cannot
read the project file:
composer.json: "conflict": {"phaenon/phn": "<0.4"} does not keep this package from being installed beside phaenon/phn 0.4.1 or 0.4.0, which cannot read its phaenon.json: the key "committed" is known from 0.5.0 on; write "phaenon/phn": "<0.5.0" under "conflict"The outputs are written all the same, and the plugin's build at the dump fails the same way, so a
composer install in the library's checkout reports it. <0.5.0, <0.5 and <=0.4.99 keep out
the same releases and pass alike; a constraint phn cannot read fails as one that "cannot be
judged". phn check, phn watch and the editors do not ask.
Where the library is installed
A project without Phaenon requires the library and gets PHP; phaenon/phn is not installed and
nothing is compiled:
composer require "acme/money:^1.0"
php -r 'require "vendor/autoload.php"; var_dump(Acme\Money\Money::sum([new Acme\Money\Money(100, "EUR"), new Acme\Money\Money(250, "EUR")])->cents);'…
- Locking acme/money (v1.0.0)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
- Installing acme/money (v1.0.0): Cloning 645a559370
Generating autoload files
…
int(350)In a project written in Phaenon, the plugin leaves the committed root as installed and writes
nothing into it. Its checker reads the library's .phn, so
what a docblock cannot carry reaches the consumer: pack() compiles to string, and the
consumer's checker still sees bytes:
namespace App;
use Acme\Money\Money;
function label(Money $price): string => strtoupper($price->pack());src/Label.phn:5:52: error P2103: argument 1 ($string) of strtoupper() expects string, bytes given
5 | function label(Money $price): string => strtoupper($price->pack());
| ^^^^^^^^^^^^^^What runs is the library's committed PHP, written by the compiler the library pinned, for the target the library names. A consumer on a much newer compiler may need a newer release of the library, if a later compiler withdrew syntax its sources use.
A release that names a committed root but came without its outputs fails the dump, before any binary is fetched, and nothing is built in its place:
phaenon/phn: acme/money v1.0.0: its phaenon.json commits the outputs of the root src, but this release is installed without them: .src/Money.php is missingA root that is not committed is built where the library is installed, if the install has it.
That is why the archive leaves tests/ out: an install from source, a git clone, has tests/,
and the plugin compiles them with warnings for the PHPUnit the consumer lacks.
Shipping sources only
A library without committed commits no outputs: .src/ is ignored, phaenon/phn stands under
require with the range of releases its sources compile with, and the plugin builds the library
in each project that installs it, for the library's own target, its findings printed as warnings.
Every consumer must then allow the plugin; a project that has not is stopped by Composer:
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.
You can run "composer config --no-plugins allow-plugins.phaenon/phn [true|false]" to enable it (true) or disable it explicitly and suppress this exception (false)
See https://getcomposer.org/allow-pluginsThat is the price the committed outputs avoid.