Skip to content

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.

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 allowed

To 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);
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.

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 allowed

Conditional (ternary) type expressions are T is U ? A : B.

generics is the angle-bracket argument list of a named type. Two flags refine what an argument may be:

  • wildcards allows * in place of the type: Example<*>;
  • hints allows a variance modifier (any identifier) before the type: Example<covariant T>.

callables is the callable (delegate) type declaration. Two flags refine it:

  • templates allows the template parameters of the callable: callable<T of U>(T): T;
  • defaults allows a default value of a parameter: callable(int $a = 42): void.

shapes is the array/object shape fields: array{ key: T }.

  • constants allows a class constant as a type: Example::CONSTANT;
  • masks allows a * in place of a part of the constant name: Example::PREFIX_*.

Literals are concrete values: numbers (42, 0xDEAD, 0.23), strings ("string"), booleans and null.

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