Start here
Phaenon and PHP
Every example on this site is written in Phaenon and in PHP. What Phaenon is, how to read the two, and how a project uses either.
Phaenon is a typed dialect of PHP 8.5 that compiles to the PHP you would write by hand. A Klass8s project can be written in Phaenon, in PHP, or in both: Symfony and Klass8s only ever load the PHP, so the container, the proxies and the events work the same either way. Klass8s itself is written in Phaenon, and its repository carries the compiled PHP too: a PHP project installs plain PHP with no compiler, while a Phaenon project also reads the .phn sources, whose types (generic queries and events, named configuration shapes) say more than PHP's.
Every example on this site exists in both languages, and both are checked: the Phaenon type-checks and compiles with a released phn, the PHP passes php -l, and where an example is a complete app, both render the YAML shown beside it. The tabs on any example switch every example on the site, and the choice is kept for your next visit. Without JavaScript the examples show Phaenon.
Reading the two
The PHP tab shows the same class as a PHP developer writes it, with the docblocks PHPStan reads. What differs in the Phaenon tab:
| Phaenon | PHP |
|---|---|
no <?php; declare(strict_types=1) is implied | both written out |
a method is its name and its parameters: replicas(): int | public function replicas(): int |
no visibility means public, on methods and constants | public written |
an expression body: replicas(): int => 2; | a block with return |
list<string>, map<string, int> in a signature | array, with the element types in a docblock |
throws LogicException after the return type | a @throws tag |
A subscriber that uses most of them:
namespace App\EventSubscriber;
use Klass8s\Bundle\EnvManagement\Env;
use Klass8s\Event\ContainerGeneratedEvent;
use LogicException;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
/** A production container without a memory limit fails the render. */
final class RequireMemoryLimitsInProd implements EventSubscriberInterface
{
__construct(#[Autowire('%kernel.environment%')] private string $environment) {}
static getSubscribedEvents(): map<string, string> => [ContainerGeneratedEvent::NAME => 'onContainer'];
onContainer(ContainerGeneratedEvent $event): void throws LogicException {
if (Env::PRODUCTION !== $this->environment) {
return;
}
$limits = $event->container->getResources()?->limits();
if (null === $limits || !$limits->has('memory')) {
throw new LogicException(sprintf('Container "%s" has no memory limit, which production requires.', $event->container->getName()));
}
}
}<?php
declare(strict_types=1);
namespace App\EventSubscriber;
use Klass8s\Bundle\EnvManagement\Env;
use Klass8s\Event\ContainerGeneratedEvent;
use LogicException;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
/** A production container without a memory limit fails the render. */
final class RequireMemoryLimitsInProd implements EventSubscriberInterface
{
public function __construct(#[Autowire('%kernel.environment%')] private string $environment) {}
/**
* @return array<string, string>
*/
public static function getSubscribedEvents(): array
{
return [ContainerGeneratedEvent::NAME => 'onContainer'];
}
/**
* @throws LogicException
*/
public function onContainer(ContainerGeneratedEvent $event): void
{
if (Env::PRODUCTION !== $this->environment) {
return;
}
$limits = $event->container->getResources()?->limits();
if (null === $limits || !$limits->has('memory')) {
throw new LogicException(sprintf('Container "%s" has no memory limit, which production requires.', $event->container->getName()));
}
}
}What Phaenon adds is types and the spelling of declarations; what a line does at run time is what the same line does in PHP. The language's documentation has the rest.
A project in Phaenon
The compiler reads the source roots phaenon.json names and writes each into a sibling directory: src/ into .src/. Composer's autoloader and Symfony's service discovery read .src/; you edit src/. Installation has the setup, which is four small changes to a Symfony application and the phaenon/phn package:
vendor/bin/phn check # type-check, write nothing
vendor/bin/phn build # compile src/ into .src/
vendor/bin/phn watch # compile on every saveThe plugin also compiles whenever Composer writes the autoloader, so composer install leaves a project ready to render. A .php file under src/ is copied into .src/ unchanged, which lets a PHP project move one class at a time; vendor/bin/phn migrate <path> turns PHP files into Phaenon. Editor support (a PhpStorm plugin, a Visual Studio Code extension) is described on phaenon.dev.
How the package reaches either kind of project
Klass8s is written in Phaenon, and its repository carries both its sources and the PHP they compile to:
| Directory | Holds |
|---|---|
src/ | the .phn sources |
.src/ | the PHP phn build writes for them, committed ("committed": ["src"] in its phaenon.json) |
config/, templates/ | the bundle's service definitions, and the templates the make commands write classes from, in PHP and, under templates/phn/, in Phaenon |
The package's composer.json maps the namespace Klass8s\ to .src/. So a **PHP project** loads plain PHP: the compiler is only a development dependency of the library, and nothing installs a compiler, a Composer plugin or a binary for you. A **Phaenon project** loads the same PHP and reads the .phn sources besides, so its type checks see the library's own types: ManifestsQuery<M> with instancesOf() and getManifestByClass() returning the class you name, method events typed by what they carry, named shapes for the processed configuration (ManifestConfig, AppConfig). The library's composer.json keeps out a phaenon/phn older than 0.5.0, the first release that reads committed outputs.
What Composer installs is the library alone: the sources, their compiled PHP, config/, templates/, the licence and the notices. The library's tests and its own documentation stay in its repository. Its check before every change compiles src/ and fails when the committed .src/ differs from what the build writes, and it builds the archive Composer installs from and fails when that archive leaves out anything a project needs (composer.json, phaenon.json, src/, .src/, config/, templates/, LICENSE, NOTICE) or carries the tests. So the PHP a project installs is the PHP the sources compile to, and nothing it needs is missing.
What stays the same
- The classes are the same classes. Namespaces, names and signatures compile as written, so
ApiDeployment::class, a constant or an attribute means the same in both languages, and a PHP class can extend or reference a Phaenon one. - Manifest classes are not
final, in either language: Klass8s subclasses them at run time for its proxies (Manifests). - Configuration is YAML and stays one file for both:
config/packages/klass8s.yamlandconfig/services.yamlare shown once on these pages. Where they name a directory, a Phaenon project names.src/. - The rendered YAML is identical. The examples' check renders both variants and compares the bytes.