Shape Types

Edit pageLast modified: 02 February 2025

Each composite type can be rigidly described by a structural type called a "shape". A shape within the PHP language can be applied to any array or object and contain either implicit or explicit keys.

array{
    a: first,
    b: second
}

warning

The use of explicit and implicit keys in one shape is not allowed and causes an exception during parsing.

array{
    named: first,
    second
}

An error similar to the one below should occur.

ParseException: Cannot mix numeric and named keys.

warning

Support for other types of keys, such as const mask (Class::CONST_*) is not currently available.

array{
    Class::CONST_*: string,
    ...
}

An error similar to the one below should occur.

ParseException: Syntax error, unexpected ":"

Optional Fields

Specifying fields (keys) allows the optionality of the presence of a field. Such fields are indicated by a question mark (?) before the colon (:) symbol: key?: Type.

Optional Key

array{
    key?: Type,
}

Optional Value

array{
    key: Type?,
}

Unsealed Shapes

Unsealed (unclosed) shapes mean that the composite type can contain additional fields beyond those described in the shape. Such types must be terminated with the " ... ".

Sealed

array{
    key: type,
}

Unsealed

array{
    key: type,
    ...
}

Typed Shapes

In addition, such shapes can describe template arguments (types) for values or for keys and values, which are described after the ellipsis (...) char and contain syntax similar to generics.

Without Arguments

array{
    user: User,
    ...
}

With Arguments

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

Attributes

Each shape field allows you to define list of additional attributes. An attribute is additional metadata for a field.

tip

Simple attribute with one argument for each shape field.

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

tip

Multiple attributes in one group.

App\Domain\User{
    #[complexity(100), skip_when_empty]
    friends: list<App\Domain\User>,
}

tip

Multiple attribute groups.

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