type-lang/types

An AST nodes of the TypeLang

2.0.0-beta1 2026-07-12 18:26 UTC

Requires

• php: ^8.4

Requires (Dev)

• phpstan/phpstan: ^2.2.5
• phpunit/phpunit: ^13.2.4

MIT

• php
• language
• ast
• nodes
• types
• type-lang

Published on Packagist.org on 2026-07-12 18:43 UTC

README

The AST node classes (TypeLang\Type\*) for TypeLang — a declarative type language inspired by static analyzers like PHPStan and Psalm.

These plain, dependency-free DTOs are the shared vocabulary of the TypeLang ecosystem: the parser produces them, the printer renders them, and the reader builds them from Reflection.

Full documentation is available at typelang.dev.

Installation

Install the package via Composer:

composer require type-lang/types

Requirements:

• PHP 8.4+

Usage

Every node extends the abstract Node class and exposes an $offset (byte offset of the token in the original source). You usually get nodes from the parser, but they can also be constructed by hand.

Identifiers and Names

use TypeLang\Type\Identifier;
use TypeLang\Type\Name;

$id = Identifier::createFromString('non-empty-string');
$id->value;     // 'non-empty-string'
$id->isVirtual; // true  (contains "-", e.g. "array-key", "positive-int")
$id->isBuiltin; // false (e.g. "int", "bool", "null")
$id->isSpecial; // false (e.g. "self", "static", "parent")

$name = Name::createFromString('\TypeLang\Type\Node');
$name->isFullyQualified; // true
$name->first->value;     // 'TypeLang'
$name->last->value;      // 'Node'

Building Type Nodes

use TypeLang\Type\Name;
use TypeLang\Type\NamedTypeNode;
use TypeLang\Type\NullableTypeNode;
use TypeLang\Type\UnionTypeNode;
use TypeLang\Type\TemplateArgumentListNode;
use TypeLang\Type\TemplateArgumentNode;

// int
new NamedTypeNode(Name::createFromString('int'));

// ?string
new NullableTypeNode(new NamedTypeNode(Name::createFromString('string')));

// int|string|null  (nested unions of the same kind are flattened)
new UnionTypeNode(
    new NamedTypeNode(Name::createFromString('int')),
    new NamedTypeNode(Name::createFromString('string')),
    new NamedTypeNode(Name::createFromString('null')),
);

// array<string, int>
new NamedTypeNode(
    name: Name::createFromString('array'),
    arguments: new TemplateArgumentListNode([
        new TemplateArgumentNode(new NamedTypeNode(Name::createFromString('string'))),
        new TemplateArgumentNode(new NamedTypeNode(Name::createFromString('int'))),
    ]),
);

Node Lists

All list containers (shape fields, template arguments, callable parameters, ...) extend NodeList and implement Countable, ArrayAccess and IteratorAggregate:

count($list);   // number of items
$list[0];       // item by offset
$list->first;   // first item
$list->last;    // last item
foreach ($list as $item) { /* ... */ }

The package covers the full type grammar — unions and intersections, callables, conditional (ternary) expressions, class-constant masks, literals, shape fields and attributes. See the documentation for the complete node reference.