3.1Design Principles

The language is defined according to the following principles.

Syntax, not semantics. This specification defines only what is well-formed. A conforming implementation MUST NOT impose restrictions on type naming, on the number of generic arguments, on the existence of a referenced class or constant, or on the logical consistency of a type. For example, the document int<string, max> is syntactically valid even though no implementation is likely to accept it semantically. Validation of such concerns MAY be performed by the consuming implementation but is out of scope for this specification.

Superset compatibility. TypeLang aims to parse every type expression accepted by PHPStan or Psalm, and to resolve ambiguities and inconsistencies between them in favour of the most permissive well-defined interpretation.

A single root. Unlike a general-purpose language, a TypeLang document is not a list of statements. It consists of exactly one Type (see Types); a document contains no declarations, no imports, and no execution.

3.2Conformance

A conforming implementation of TypeLang MUST accept every document that this specification defines as valid, and MUST reject every document that this specification defines as invalid. A conforming implementation MAY additionally accept extensions to the grammar defined herein, provided that every document accepted by such an extension would otherwise be rejected by this specification; an implementation MUST NOT extend the grammar in a way that causes a document valid under this specification to be assigned a different syntactic structure.

This specification defines only syntax. Whether a given document is semantically meaningful (for example, whether a referenced class exists, or whether the number of supplied generic arguments matches the number expected by a referenced type) is a matter for the consuming implementation and is outside the scope of conformance to this specification.

The illustrative error messages that accompany counter-examples throughout this specification (see Examples and Counter-Examples) are non-normative. A conforming implementation is not required to reproduce their exact wording, but MUST reject the corresponding document.

3.3Document

A TypeLang Document consists of a single Type expression. The source text of a document, after removal of Ignored tokens, MUST be described in full by a single Type; any trailing tokens that cannot be consumed by Type constitute a syntax error.

The following is an example of a valid document combining several features of the language:

array{
    id: int<1, max>,
    name: non-empty-string,
    roles: list<App\Domain\Role>,
    parent?: ?self,
    ...
}

3.4Relationship to Other Tools

TypeLang is a strict syntactic superset of the common subset shared by PHPStan and Psalm. Notable extensions beyond what those tools accept include, among others:

• Binary (0b1010), octal (0o42, legacy 042) and hexadecimal (0xDEAD) integer literals.
• Escape, hexadecimal and Unicode sequences inside double-quoted string literals.
• Global constant masks such as JSON_*.
• Attributes (#[...]) on template arguments, shape fields and callable parameters.
• A uniform conditional (ternary) type syntax that also permits comparison operators and Yoda-style operands.

A detailed feature-by-feature comparison is maintained alongside the project documentation and is out of scope for this specification.

3.5A Note on Examples

Throughout this document, code examples are presented in fenced blocks. Examples that denote valid documents are shown directly; examples that denote a syntax error are explicitly marked as counter-examples and are accompanied by the kind of error a conforming parser is expected to raise.

3.6Security and Implementation Considerations

TypeLang documents are frequently extracted from sources that an implementation does not fully trust, such as docblocks or attributes authored by third-party packages. Implementers SHOULD take the following into account.

Recursion depth. Several productions of this grammar are directly or indirectly recursive (for example, a parenthesized Type, a generic TemplateArgument, a shape field value, and a callable parameter or return type may each themselves contain an arbitrary Type). An implementation that evaluates such productions using unbounded native recursion MAY be vulnerable to stack exhaustion when parsing a maliciously or accidentally deeply nested document. An implementation SHOULD impose an implementation-defined limit on nesting depth and MUST, upon reaching that limit, reject the document rather than exhibit undefined behaviour.

Input length. This specification does not limit the length of a Name, the number of TemplateArguments, the number of ShapeFields, or the overall length of a document. An implementation intended for use with untrusted input SHOULD impose implementation-defined limits on these quantities.

Numeric ranges. As described in Integer, an integer literal’s value is clamped to the representable range of the implementation’s platform integer while the raw lexeme is preserved. Implementations that convert a FloatLiteral to a native floating-point representation are subject to the usual limitations of that representation (precision loss, rounding, infinities) and SHOULD document their behaviour in such cases.

4.1Source Text

TypeLang documents are interpreted from a source text, which is a sequence of SourceCharacter. Any Unicode code point may appear in the source text.

For the purposes of the lexical grammar, a letter is any of the ASCII characters a through z and A through Z, together with every byte in the range U+0080 through U+00FF.

4.2Ignored Tokens

Ignored tokens improve readability and separate lexical tokens, but are otherwise insignificant. Any amount of Ignored MAY appear before and after every lexical Token.

4.3Lexical Tokens

A TypeLang document is composed of several kinds of indivisible lexical tokens, defined here by patterns of source characters. Lexical tokens MAY be separated by Ignored tokens and are used as the terminal symbols of the syntactic grammar.

ExampleTypeName

non-empty-string

true-type

Counter Example № 142type

ParseException: Syntax error, unexpected "type"

Counter Example № 2TrUe

4.4Literal Tokens

A literal denotes a single, specific PHP value. The lexical grammar recognises boolean, null, integer, floating-point and string literals.

1_000_000

0b1010_1101

0o42

0xDEAD_BEEF

Counter Example № 30b101042

ParseException: Syntax error, unexpected "42"

0.9

.9

1.

10e-2

Counter Example № 4.

ParseException: Syntax error, unexpected "."

'I am a single-quoted string with an escaped \' quote'

"I am a double-quoted string with an escaped \" quote"

5.1Type Precedence

A Type is parsed as an operator-precedence hierarchy. From the loosest-binding construct to the tightest, the levels are:

1. Conditional (ternary) types — … is … ? … : …
2. Union types — A | B
3. Intersection types — A & B
4. Nullable prefix — ?A
5. Postfix list and offset access — A[], A[K]
6. Primary types — names, literals, callables, shapes, and parenthesized types

Each level is defined in terms of the next-tighter level, so that, for example, intersection binds more tightly than union and A & B | C is parsed as (A & B) | C. Parentheses (see Primary Types) MAY be used to override this precedence.

5.2Conditional Types

A conditional type (also called a ternary type) selects between two types based on a comparison between a subject and a comparand. It is written as the subject, an operator, the comparand, a ?, the type chosen when the condition holds, a :, and the type chosen otherwise.

T is string ? int : bool

The negative-equality operator is spelled is not. At the lexical level, the two words MUST be separated only by horizontal whitespace and are scanned as a single token; no line terminator may appear between them.

T is not string ? int : bool

Either the subject or the comparand MAY be a Variable instead of a Type, including in “Yoda” order, where the variable appears on the right:

$value is array ? non-empty-array : null

array is $value ? non-empty-array : null

In addition to is and is not, the relational operators <, >, <= and >= MAY be used as the condition operator. This is an extension beyond what PHPStan and Psalm accept; see Relationship to Other Tools.

5.3Logical Types

TypeLang, like PHP, supports two composite (logical) type constructors — union and intersection — together with a nullable shorthand.

A | B | C

A & B & C

(A & B) | C

(A | B) & C

?Example

Counter Example № 5Example?

ParseException: Syntax error, unexpected "?"

5.4List and Offset Access Types

A PrimaryType MAY be followed by zero or more postfix suffixes, applied left to right.

User[]

User[][]

Counter Example № 6User[int]

T['offset']

T[U]

array{int, string}[0]

T<U>[object{key: int, ...}]

Counter Example № 7Collection[[Some]]

ParseException: Syntax error, unexpected "["

5.5Primary Types

A primary type is the tightest-binding form. It is one of: a parenthesized Type, the $this type, a literal type, a callable type (see Callable Types), or a named type.

A parenthesized type is used to override precedence; it denotes exactly the type it encloses:

(A | B) & C

The $this variable, when used as a primary type, denotes the current object type:

$this

5.6Names and Namespaces

A Name is a sequence of one or more Identifier segments joined by the namespace separator (\), mirroring PHP namespaces. A fully-qualified name additionally begins with a leading separator.

Example\Name

\Absolute\Type\Name

A separator MAY appear at the start of a name or between two segments, but MUST NOT appear at the end.

Reserved words within names. The reserved words true, false, null and is (see Reserved Words) MAY appear as an Identifier segment of a Name. In isolation, such a word is scanned as a literal or operator and so cannot stand as a bare type name; but in a qualified position — following a separator or another segment — it denotes a name segment. This makes \null a reference to a type named null, distinct from the null literal.

Counter-example. A name cannot end with a separator.

Counter Example № 8Example\Name\

ParseException: Syntax error, unexpected end of input

5.7Named Types

A named type is a Name optionally followed by either a list of template arguments (generics) or a shape body. A bare named type is the most common type of all:

Path\To\ExampleClass

This grammar imposes no restriction on which names are valid; int, string, list, non-empty-string, and any user-defined class name are all parsed identically as named types. Whether a name refers to a built-in type, a class, an interface, an enum, or a type alias is a semantic concern for the implementation and is outside the scope of this specification.

5.8Generic Types

A generic type supplies a named type with one or more template arguments, each of which is itself a Type. Arguments are enclosed in angle brackets (< and >) and separated by commas. A trailing comma is permitted.

Validating the number of arguments, their bounds, and their nesting is the responsibility of the implementation, not of this grammar, which imposes no such limits.

Path\To\ExampleClass<T, U>

iterable<int<0, max>, Collection<User>>

HashMap<Request, User,>

Counter-example. At least one argument is required, and a leading comma is not permitted.

Counter Example № 9example<>

ParseException: Syntax error, unexpected ">"

HashMap<array-key, covariant Request>

Counter Example № 10HashMap<array-key, some covariant Request>

ParseException: Syntax error, unexpected "Request"

Counter Example № 11HashMap<is Request>

ParseException: Syntax error, unexpected "Request"

HashMap<#[name("key")] T, #[name("value")] U>

5.9Literal Types

A literal type denotes the singleton type containing exactly one value, or, in the case of a ConstantMask, a well-defined family of such singleton types. The boolean, null, integer, floating-point and string forms correspond directly to the literal tokens of the same name:

true

42

"Hello World"

A ClassConstant and a ConstantMask (see Constant Types, below) are likewise literal types, since each references a single PHP constant or a well-defined family of PHP constants. An unqualified reference to a global constant, by contrast, has no dedicated grammar of its own; it is described in Global Constants.

5.10Constant Types

TypeLang provides two dedicated grammar forms for referencing constants: a ClassConstant and a ConstantMask. Together with the naming convention for a single global constant described below, this specification uses the term constant type loosely to refer to all three collectively; only ClassConstant and ConstantMask, however, are formal non-terminals of the grammar.

JSON_THROW_ON_ERROR

pcov\version

ClassName::CONSTANT_NAME

Path\To\ClassName::ANOTHER_CONSTANT_NAME

Counter Example № 12ClassName::SOME\ANY

ParseException: Syntax error, unexpected "\"

JSON_*

Path\To\ClassName::PREFIX_*

Path\To\ClassName::*

Counter Example № 13*

ParseException: Syntax error, unexpected "*"

Counter Example № 14Path\To\ClassName::PREFIX_*_SUFFIX

ParseException: Syntax error, unexpected "_SUFFIX"

6.1Shape Types

A shape rigidly describes the individual elements of a composite value, such as the keys of an array or the properties of an object. A shape is written as a named type immediately followed by a brace-enclosed body; the name — commonly array, object, or list, but any name is accepted — describes the container, and the body describes its elements.

array{
    a: First,
    b: Second
}

Custom\Type{
    id: int,
    name: string
}

An empty shape body describes a container with no elements:

array{}

array{ name: First, count: Second }

array{ 1: First, 42: Second }

array{ "name-some": First, "escape\nchars": Second }

array{ First, Second }

array{ Path\To\ClassName::CONSTANT_NAME: First, JSON_*: Second }

Counter Example № 15array{ named: First, Second }

ParseException: Cannot mix explicit and implicit shape keys

Counter Example № 16array{ 1: int, 2: int, 1: string }

ParseException: Duplicate key "1"

array{ key?: Type }

array{ key: ?Type }

array{ key: Type, ... }

array{ ... }

array{ user: User, ...<string, object> }

App\Domain\User{
    #[name("user_name")]
    userName: non-empty-string,
    #[skip_when_empty]
    friends: list<App\Domain\User>,
    ...
}

6.2Callable Types

A callable type describes a function-like value. It is a name — commonly callable or Closure, but any name is accepted — followed by a parenthesized, possibly empty, parameter list, and an optional return type introduced by a colon.

callable()

callable(): void

Closure(int<0, max>, callable(?C): mixed): void

callable(Type)

callable(Type $name)

callable($name)

callable(A $a, B, C)

callable(T&)

callable(T &$name)

Counter Example № 17callable(&T)

ParseException: Syntax error, unexpected "T"

callable(T=)

callable(T &$name=)

callable(...T)

callable(T ...$name)

callable(T &...$name)

Counter Example № 18callable(...T...)

ParseException: Either prefix or postfix variadic syntax should be used, but not both

Counter Example № 19callable(T ...$name=)

ParseException: Cannot have variadic param with a default

Example\Functor(#[type<int8>] int $a): void

6.3Attributes

An attribute attaches arbitrary, implementation-defined metadata to the construct it precedes. The syntax mirrors PHP attributes: each attribute is a name optionally followed by a parenthesized list of arguments, and each argument is itself an arbitrary Type — including, recursively, a type that carries attributes of its own.

Attributes are written in groups delimited by #[ and ]. A construct MAY carry several attributes within one group, separated by commas, and several groups in sequence. Attributes may be attached to a template argument, a shape field, or a callable parameter.

A single attribute with one argument:

Example\Functor(#[type<int8>] int $a): void

Several attributes within one group:

HashMap<#[name("key"), out] T>

Several groups in sequence:

array{
    #[serialize("onSerialize")]
    #[deserialize("onDeserialize")]
    test?: App\Domain\User,
}

Counter-example. An attribute name must be a valid Name; a literal is not permitted in that position.

Counter Example № 20Collection<#[42] User>

ParseException: Syntax error, unexpected "42"

A.1Context-Free Grammar

A context-free grammar consists of a number of productions. Each production has an abstract symbol, called a non-terminal, as its left-hand side, and one or more sequences of non-terminal symbols and terminal characters as its right-hand side.

Starting from a single goal non-terminal (Type, for TypeLang), the grammar describes a language: the set of character sequences obtained by repeatedly replacing a non-terminal with one of its right-hand sides until only terminals remain.

Terminals are written in a monospace font, either as a specific character or sequence (for example | or is), or as prose describing a code point (for example "New Line (U+000A)").

A production with a single definition is written on one line:

A production with several alternative definitions is written as a list:

A definition may refer to itself to describe a repetitive sequence:

A.2Lexical and Syntactic Grammar

TypeLang is defined by two grammars. The lexical grammar matches patterns of source characters into tokens; the syntactic grammar matches patterns of tokens into the abstract syntax tree.

A lexical grammar production is distinguished by a double colon ::. No Ignored characters may appear between the terminals of a lexical production.

A syntactic grammar production is distinguished by a single colon :. Ignored tokens may appear before or after any terminal token of a syntactic production.

A.3Grammar Notation

one of. A production whose alternatives are each a single terminal may be written compactly with the phrase “one of”:

is shorthand for

Optionality. A subscript-style suffix ? denotes an optional symbol: one sequence including it, and one excluding it.

is shorthand for

Lists. A suffix * denotes zero or more repetitions of a symbol; a suffix + denotes one or more. For example, Identifierlist matches a non-empty run of Identifier.

Constraints (but not). The phrase “but not” excludes certain expansions that would otherwise be permitted.

means that a NonReserved may be any Name except those three sequences.

Lookahead Restrictions. A restriction of the form [lookahead != X] states that the production must not be followed by X. Lookahead restrictions remove ambiguity and, together with longest-match scanning, ensure a single valid lexical analysis. For example:

makes explicit that a NameToken is always the longest possible sequence, and cannot be followed by another NameContinue character.

Overlapping Alternatives. The order in which a production’s alternatives are written carries no meaning by itself. Some alternatives, however, cannot be told apart by their first symbol alone — for example, ClassConstant, ConstantMask, CallableType and NamedType (see Primary Types) all begin with a Name. In every such case, this specification identifies, either through an explicit lookahead restriction or through an accompanying Note, the further input that determines which alternative applies at that position — typically the single token that follows a fully recognized Name or Identifier. The grammar described by this specification is unambiguous in the sense that, once that further input is consulted, at most one alternative can match at any position. This specification prescribes neither a parsing algorithm nor an implementation strategy; it is satisfied by any implementation — whether based on recursive descent, an LL(k) or LALR parser generator, a parsing expression grammar, or any other technique — that accepts exactly the documents, and performs exactly the disambiguation, described herein.

A.4Grammar Semantics

Some productions are accompanied by a Static Semantics description, which explains how a conforming implementation is to interpret the matched source beyond merely accepting it — for example, how the radix of an integer literal is determined, or how an out-of-range value is clamped. Static semantics never alter which documents are accepted; they only describe the value or node that a valid document denotes.

A.5Examples and Counter-Examples

Code blocks in this document illustrate the grammar. A block presented without qualification denotes a valid document. A block explicitly introduced as a counter-example denotes an invalid document, and is typically followed by the kind of error a conforming implementation is expected to raise. Such error messages are illustrative and non-normative; their exact wording is not prescribed by this specification, and an implementation MAY report a different message, provided that it rejects the document (see Conformance).