Parser
Feature toggling
You can enable or disable a set of parser features if your task requires only partial support of the functionality. This is convenient for implementing a stricter subset of the syntax — for example, allowing plain PHP type declarations while rejecting PHPStan/Psalm-style generics.
Configuring features
Section titled “Configuring features”All flags live on a single immutable value object, TypeLang\Parser\TypeParserFeatures,
which is the first constructor argument of TypeParser. Every flag defaults
to true.
use TypeLang\Parser\TypeParser;use TypeLang\Parser\TypeParserFeatures;
$parser = new TypeParser(new TypeParserFeatures( literals: false,));
$parser->parse('42');// throws FeatureNotEnabledException: Literals feature is not allowedTo override one or more flags on an existing parser, use TypeParser::with()
instead — it returns a new parser sharing everything else with the original one:
$parser = new TypeParser();
$strict = $parser->with( generics: false, shapes: false,);TypeParserFeatures itself also has a with() method for deriving a new
feature set from an existing one, keeping every flag not explicitly passed:
$features = new TypeParserFeatures() ->with(unions: false);Available features
Section titled “Available features”| Flag | Enables syntax |
|---|---|
unions |
T|U |
intersections |
T&U |
nullables |
?T |
lists |
T[] |
offsets |
T[K] |
conditions |
T is U ? A : B |
generics |
Example<T> |
wildcards |
Example<*> |
hints |
Example<covariant T, contravariant U> |
callables |
fn(): void |
templates |
callable<T of U = V>(T): T |
defaults |
callable(T $a = U): V |
shapes |
array{ key: T } |
constants |
Example::CONSTANT |
masks |
Example::PREFIX_*, Path\To\* |
literals |
42, "foo", 0.23, true, null, … |
A flag turns off exactly one language feature. Flags do not depend on each
other: when generics is disabled, Example<T> is rejected and wildcards
and hints have nothing to apply to.
Composite types
Section titled “Composite types”unions, intersections, nullables, lists, offsets and conditions
control the operators that build a type out of other types.
$parser = new TypeParser(new TypeParserFeatures( unions: false,));
$parser->parse('T|U'); // rejected$parser->parse('?T'); // still allowedConditional (ternary) type expressions are
T is U ? A : B.
Generics
Section titled “Generics”generics is the angle-bracket argument list of a named type. Two flags
refine what an argument may be:
wildcardsallows*in place of the type:Example<*>;hintsallows a variance modifier (any identifier) before the type:Example<covariant T>.
Callables
Section titled “Callables”callables is the callable (delegate) type declaration. Two flags refine it:
templatesallows the template parameters of the callable:callable<T of U>(T): T;defaultsallows a default value of a parameter:callable(int $a = 42): void.
Shapes
Section titled “Shapes”shapes is the array/object shape fields: array{ key: T }.
Constants
Section titled “Constants”constantsallows a class constant as a type:Example::CONSTANT;masksallows a*in place of a part of the constant name:Example::PREFIX_*.
Literals
Section titled “Literals”Literals are concrete values: numbers (42,
0xDEAD, 0.23), strings ("string"),
booleans and null.
Behavior of disabled features
Section titled “Behavior of disabled features”A disabled feature is reported as a
TypeLang\Parser\Exception\FeatureNotEnabledException (a ParsingException)
by both parse() and partial():
$parser = new TypeParser(new TypeParserFeatures(unions: false));
$parser->partial('T|U');// throws FeatureNotEnabledException: Unions feature is not allowed