Getting startedInstall

Getting started

Install

Install phn through its Composer plugin, which pins the compiler in composer.lock, or as one binary for macOS, Linux or Windows.

The compiler, phn, is one static binary. In a Composer project the phaenon/phn plugin brings it: the binary for your platform, checked against a SHA-256 the package pins, so that composer.lock pins the compiler as it pins every other dependency. Outside Composer you download the binary yourself.

With Composer

Allow the plugin, then require it:

composer config allow-plugins.phaenon/phn true
composer require phaenon/phn
./composer.json has been updated
Running composer update phaenon/phn
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking phaenon/phn (v0.7.2)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Downloading phaenon/phn (v0.7.2)
  - Installing phaenon/phn (v0.7.2): Extracting archive
…
Using version ^0.7.2 for phaenon/phn

Composer runs a plugin only once the project allows it. Without the first command, composer require --no-interaction stops with "phaenon/phn contains a Composer plugin which is blocked by your allow-plugins config"; in a terminal, Composer asks instead, and answering yes writes the same setting into composer.json:

"config": {
    "allow-plugins": {
        "phaenon/phn": true
    }
}

The package is on Packagist. Its version is the compiler's: phaenon/phn 0.7.2 brings phn 0.7.2.

require, not require-dev

An application keeps the compiled PHP out of its repository and builds it where it is installed, so the plugin belongs in require. A production install runs without the development packages:

composer install --no-dev

With the plugin in require, that install compiles the sources as it writes the autoloader. With the plugin in require-dev, the same install leaves it out, nothing is compiled, and the autoloader points at an output directory that does not exist.

The one exception is a library that commits its compiled PHP, so that projects without phn can install it: there the plugin is a development tool, in require-dev with an exact version. Publishing a library covers that case.

What the plugin does

It links vendor/bin/phn, a small PHP launcher that runs the binary with your arguments, standard streams and exit status. Use it wherever this documentation writes phn.

It fetches the binary when it is first needed: at the first autoload dump of a project that has a phaenon.json, or at the first run of vendor/bin/phn, whichever comes first.

vendor/bin/phn version
phaenon/phn: Downloading phn 0.7.2 (phn-darwin-arm64) from https://github.com/phaenonlang/phaenon/releases/download/v0.7.2/phn-darwin-arm64
phn 0.7.2

The download comes from the compiler's GitHub release. The plugin checks it against the SHA-256 that phaenon/phn carries for each platform (composer/checksums.json in the package) and refuses a file that does not match. It keeps the binary in Composer's cache, under phaenon-phn/<version>/, and installs it as vendor/phaenon/phn/bin/phn. A second project on the same machine takes it from the cache.

It builds when Composer writes the autoloader. Every composer install, composer update and composer dump-autoload compiles first the installed packages that have a phaenon.json, then the project itself, so that the autoloader is written over outputs that exist:

Generating autoload files
> phn build
1 files compiled, 1 written, 0 files copied, 0 stale outputs removed
Generated autoload files

A project with nothing to build, its own or installed, makes the plugin do nothing: it neither fetches nor runs the binary. A build that fails stops the Composer command, after phn has printed what failed.

Settings

The root project's composer.json can change three things. An installed package's settings are ignored.

  • PHN_BINARY=/path/to/phn in the environment runs another binary, a build from source for example. Nothing is downloaded and no checksum is checked.
  • "extra": {"phaenon": {"binary-url": "…"}} downloads the binary from a mirror instead of GitHub. The value is a URL template: {version} and {file} are filled in. phaenon.dev mirrors every release:
"extra": {
    "phaenon": {
        "binary-url": "https://phaenon.dev/releases/{version}/{file}"
    }
}
  • "extra": {"phaenon": {"build": false}} leaves the project's own build to its scripts or CI. Installed packages are still built.

The checksum decides in every case: a mirror serves the same files, and a file that differs from the pinned one is refused.

The binary alone

Each release has one file per platform:

PlatformFile
macOS, Apple siliconphn-darwin-arm64
macOS, Intelphn-darwin-amd64
Linux, x86-64phn-linux-amd64
Linux, ARM64phn-linux-arm64
Windows, x86-64phn-windows-amd64.exe

The Linux binaries are statically linked, so they run on any distribution, Alpine included. The download page lists every release with the SHA-256 of each file. Download yours, compare the checksum and run it:

curl -fLO https://phaenon.dev/releases/0.7.2/phn-darwin-arm64
shasum -a 256 phn-darwin-arm64
a341381b13e87cfa42bd36c9524a74547eb459cab8fb5b1e11f9215d74d6372f  phn-darwin-arm64
chmod +x phn-darwin-arm64
./phn-darwin-arm64 version
phn 0.7.2

Then put it on your PATH under the name phn. On Linux, sha256sum prints the same checksum. The same sums are in composer/checksums.json at the release's tag, and the files are on the GitHub release too. A file at phaenon.dev never changes once published: a new build is a new version.

From source

With Go 1.27 or newer:

go install github.com/phaenonlang/phaenon/cmd/phn@v0.7.2

A build from source calls itself dev: phn version prints phn dev.

The release files are reproducible. In a clone of the compiler's repository at the release's tag, one command builds all seven with the Go toolchain go.mod pins and compares them with the checksums the plugin pins:

go run ./tools/release -version 0.7.2 -out dist -verify
toolchain go1.27.3
cdeac50989c9d4abf598f6ece4a11b3c7e7daae18a1f71cdc4c22f03c2861988  phn-darwin-amd64
a341381b13e87cfa42bd36c9524a74547eb459cab8fb5b1e11f9215d74d6372f  phn-darwin-arm64
…
7 assets match composer/checksums.json

PHP versions

  • The code phn writes runs on PHP 8.5 or 8.6, the project's target. The target is "php" in phaenon.json, else the lowest version composer.json's require.php admits, else PHP 8.5 with a warning. phaenon.json says more.
  • The plugin runs under the PHP that runs Composer: PHP 8.3 or newer, with Composer 2.3 or newer.
  • The checker reads the extensions of the local php (PHN_PHP names another binary), which should be as new as the target. An older one makes phn check warn, P4012.

phn itself is a Go program, and the signatures of PHP's own functions and classes are built into it. Without a php to ask, it knows the extensions that ship with PHP's source and warns that it read no others, P4007.

Next

A first project takes an empty Composer project to a class written in Phaenon, tested and analysed. To bring an existing project over, see Migrate a PHP project.