ToolingPublishing a library

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 holdssrc/*.phn and .src/*.phpsrc/*.phn
A project without Phaenon getsThe compiled PHP, ready to loadNothing it can load without the plugin
A project written in Phaenon getsThe compiled PHP, and the checker reads the .phnIts plugin builds the library at every autoload dump
phaenon/phn in the library's composer.jsonrequire-dev, one exact releaserequire, 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
└── .gitignore
src/Money.phnyou write
namespace 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);
}
.src/Money.phpphn build writes
<?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);
    }
}
src/CurrencyMismatch.phn
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-plugins question. The release is exact because two releases may write different bytes for the same source, and the committed bytes come from one compiler.
  • The conflict keeps out the compilers that cannot read the sources. It applies only where phaenon/phn is 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 knows committed, and phn build checks it (below).
  • No composer.lock is 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-ignore

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

Keep .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 -t
  • phn build takes 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 --check and phn fix --check rebuild 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 no tests/.

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 missing

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

That is the price the committed outputs avoid.