Skip to content

Extending

Expanders

An expander turns a type into the type of the data it takes, for the messages sent to clients. A class is shown as the object{...} of its fields, a backed enum as the values of its cases: the client sees what to send, not the classes of the application. See errors for the built-in expansions.

An expander returns the expansion of a type it supports, null passes the type to the next expander. Expanders of the user are tried before the built-in ones.

A type of your own is shown as it is written, unless an expander expands it. A type wrapped by a decorator is expanded as it is built, unless an expander supports the wrapper. An expander that throws leaves the message without the type (Value 42 is invalid), the error of the expander is not reported.

use TypeLang\Mapper\Mapper;
use TypeLang\Mapper\Type\Expander\TypeExpanderInterface;
use TypeLang\Mapper\Type\TypeInterface;
use TypeLang\Type\Name;
use TypeLang\Type\NamedTypeNode;
use TypeLang\Type\TypeNode;
final class UuidTypeExpander implements TypeExpanderInterface
{
public function tryExpand(TypeInterface $type, /* ... */): ?TypeNode
{
if (!$type instanceof UuidType) {
return null;
}
// uuid is shown as: string
return new NamedTypeNode(new Name('string'));
}
}
$mapper = new Mapper(expanders: [new UuidTypeExpander()]);

A type with nested types expands them by the context: $context->expand() expands a nested type one level deeper. The fields over expectedTypeMaxFields and at expectedTypeDepth are cut by the mapper for any expansion.

final class MoneyTypeExpander implements TypeExpanderInterface
{
public function tryExpand(TypeInterface $type, ExpandContext $ctx): ?TypeNode
{
if (!$type instanceof MoneyType) {
return null;
}
// money is shown as: object{amount: int, currency: 'EUR'|'USD'}
return new NamedTypeNode(
name: new Name('object'),
fields: new FieldListNode([
new NamedFieldNode(
new Identifier('amount'),
new NamedTypeNode(new Name('int')),
),
new NamedFieldNode(
new Identifier('currency'),
// the type of the currency, expanded by the mapper
$ctx->expand($type->currency),
),
]),
);
}
}