LanguageWhat Phaenon refuses

Language

What Phaenon refuses

The PHP constructs a .phn file may not use, the diagnostic for each, what to write instead, and what phn fmt and phn migrate rewrite for you.

A .phn file is PHP, minus a short list of constructs that defeat a type checker or that PHP keeps only for compatibility: the open tag, dynamic scope, the alternative syntax, a few old spellings, tabs and untyped declarations. Each is a compile error with its own message, and most have a one-line replacement. Nothing is removed from PHP itself: PHP files in the same project, and the vendor code they call, use whatever PHP allows.

At a glance

you write
namespace App;

final class Settings
{
    var $cache = [];

    load(string $file): array<mixed> {
        global $config;
        extract($config);

        return compact('file');
    }
}
$ phn checkexit 1
src/Example.phn:5:5: error P1001: `var` is not available in Phaenon; use public
    5 |     var $cache = [];
      |     ^^^
src/Example.phn:5:9: error P2516: property App\Settings::$cache has no type
    5 |     var $cache = [];
      |         ^^^^^^^^^^^
src/Example.phn:8:9: error P1001: global is not available in Phaenon; use explicit parameters or a service
    8 |         global $config;
      |         ^^^^^^^^^^^^^^^
src/Example.phn:9:9: error P1001: extract() is not available in Phaenon; use explicit assignments
    9 |         extract($config);
      |         ^^^^^^^^^^^^^^^^
src/Example.phn:11:16: error P1001: compact() is not available in Phaenon; use an explicit array literal
   11 |         return compact('file');
      |                ^^^^^^^^^^^^^^^
1 files checked: 5 errors, 0 warnings

The list

ConstructReported asWrite instead
<?php at the startP1000, a syntax errornothing: a .phn file is code from its first byte
?> and inline HTMLP1000, a syntax errora template in a separate file
global $xP1001a parameter, a constructor argument or a service
goto and labelsP1001loops, break, continue, early returns
eval()P1001code generated at build time
extract(), compact(), get_defined_vars()P1001explicit assignments and array literals
$$name, ${'name'}P1001a map<string, mixed>
"${name}" interpolationP1001"{$name}"
if: … endif; and the other alternative syntax (while, for, foreach, switch, declare)P1001braces
var $xP1001public $x, with a type
list($a, $b) = …P1001[$a, $b] = …
a tab outside a string or a comment's textP1005, once per filespaces
a parameter, return or property without a type, a bare arrayP2516the type; mixed and array<mixed> when that is what you mean
fun, is, as, as?P1001a method without a keyword; PHP's own type tests
THROWS, TYPE, List<int>, (BYTES)P1006throws, type, list<int>, (bytes)

P1001 and P1006 messages say what to write instead. P1000 is the code of every syntax error, which stops the check of that file at the first one.

The open tag and inline HTML

A .phn file is code from byte 0. It has no <?php, no closing ?>, and no HTML outside the tags; declare(strict_types=1) is implied, and the compiler writes it into every output. A template stays a PHP or Twig file of its own.

Dynamic scope

global, extract(), compact(), get_defined_vars(), variable variables and eval() make a variable's existence or its type depend on run-time data, which no checker can follow. Each has a direct replacement: pass what a function needs, build arrays with literals, and use a map where the keys are data.

Old spellings

The alternative syntax (if (…): … endif;), var and list() are PHP that has a shorter or more common form. Phaenon keeps one form of each: braces, a visibility, and […] destructuring.

The long casts are the same case. (integer), (boolean), (double) and (binary), which PHP 8.5 deprecates, and (real) and (unset), which PHP 8 refuses, are P1001. Write (int), (bool), (float) and (string); phn fmt rewrites the long ones. (unset) $x has no cast to become: write null for its value, or unset($x); as a statement.

you write
namespace App;

function size(string $input): int {
    return (integer) $input;
}
$ phn checkexit 1
src/Example.phn:4:12: error P1001: (integer) is not available in Phaenon; use (int), which phn fmt writes
    4 |     return (integer) $input;
      |            ^^^^^^^^^
1 files checked: 1 errors, 0 warnings

Tabs

Phaenon code is indented with spaces, as PER Coding Style requires. A tab outside a string's content or a comment's text is P1005, reported once per file at the first tab. Tabs inside strings, heredocs and comments are left alone.

Untyped declarations

Every parameter, return and property has a type, and a bare array names what it holds. mixed is a type you write when you mean it, never one the checker assumes:

you write
namespace App;

final class Counter
{
    public $count = 0;

    add($step) {
        $this->count += $step;
    }
}
$ phn checkexit 1
src/Example.phn:5:12: error P2516: property App\Counter::$count has no type
    5 |     public $count = 0;
      |            ^^^^^^^^^^
src/Example.phn:7:5: error P2516: add() has no return type
    7 |     add($step) {
      |     ^
src/Example.phn:7:9: error P2516: parameter $step of add() has no type
    7 |     add($step) {
      |         ^^^^^
1 files checked: 3 errors, 0 warnings

A closure's parameters may stay untyped where the call gives them a type, as in array_map(fn ($u) => $u->email, $users). A method that overrides one from PHP code may keep a bare array when its parent's docblock says what the array holds.

Phaenon's own words

The words Phaenon adds to PHP are written in lower case: throws, nothrow, type, of, in, out, class<T>, list<T>, map<K, V>, bytes and the cast (bytes). Where only the word can stand, another case is read as the word and reported, P1006:

you write
namespace App;

TYPE Ids = List<int>;

function first(Ids $ids): int THROWS \OutOfRangeException => $ids[0] ?? throw new \OutOfRangeException('empty');
$ phn checkexit 1
src/Example.phn:3:1: error P1006: `TYPE` is Phaenon's `type`, written in lower case; phn fmt rewrites it
    3 | TYPE Ids = List<int>;
      | ^^^^
src/Example.phn:3:12: error P1006: `List` is Phaenon's `list`, written in lower case; phn fmt rewrites it
    3 | TYPE Ids = List<int>;
      |            ^^^^
src/Example.phn:5:31: error P1006: `THROWS` is Phaenon's `throws`, written in lower case; phn fmt rewrites it
    5 | function first(Ids $ids): int THROWS \OutOfRangeException => $ids[0] ?? throw new \OutOfRangeException('empty');
      |                               ^^^^^^
1 files checked: 3 errors, 0 warnings

Where the same spelling can be a name, it is the name: a method type(), a class Throws, a constant NOTHROW. Map and Bytes are class names like any other, so a project can have a class Map: Map<string, int> is that class, and where no class of that name exists it is P2001, with a message that says Phaenon's type is written map. PHP's own words keep PHP's rules, so INT and FUNCTION still compile.

The words of earlier releases are gone: fun before a method (0.4.0 removed it; a method needs no keyword), and the operators is, as and as? (PHP's tests instead, see type tests and narrowing).

What stays PHP

Everything not listed here is PHP and compiles as PHP: references, include and require, static variables, @, $GLOBALS, __halt_compiler(), every class, enum, attribute and property-hook feature of PHP 8.5.

What the tools rewrite

phn fmt and phn migrate fix part of the list mechanically:

Rewritten byWhat
phn migrateremoves <?php, a trailing ?> and declare(strict_types=1); replaces tabs with spaces; lifts function off methods; lifts docblock types into the signature, and types a bare array as array<mixed>
phn fmtreplaces tabs with spaces; lifts function off methods; rewrites fun, is, as and as?; writes Phaenon's words in lower case

The rest is yours to change: global, goto, eval(), extract() and compact(), variable variables, the alternative syntax, var, list(), and the types the checker asks for. phn check lists each place. See migrate a PHP project and formatting and fixers.

See also