Skip to content

Extending

Custom types

A type converts a value in both directions. A builder creates the type of a type node, such as of a name money or of a generic collection<T>.

A type implements TypeInterface: a pair of methods per direction.

Method Does
isDenormalizable(), isNormalizable() checks the value, never throws: it chooses the branch of a union
denormalize(), normalize() converts the value or throws an InvalidValueException
use TypeLang\Mapper\Context\Context;
use TypeLang\Mapper\Exception\InvalidValueException;
use TypeLang\Mapper\Type\TypeInterface;
// '100 USD' <-> Money { amount: 100, currency: 'USD' }
final class MoneyType implements TypeInterface
{
public function isDenormalizable(mixed $value, Context $context): bool
{
return \is_string($value)
&& \preg_match('/^\d+ [A-Z]{3}$/', $value) === 1;
}
public function denormalize(mixed $value, Context $context): Money
{
if (!$this->isDenormalizable($value, $context)) {
throw InvalidValueException::becauseInvalidType($value);
}
[$amount, $currency] = \explode(' ', $value);
return new Money((int) $amount, $currency);
}
public function isNormalizable(mixed $value, Context $context): bool
{
return $value instanceof Money;
}
public function normalize(mixed $value, Context $context): string
{
if (!$value instanceof Money) {
throw InvalidValueException::becauseInvalidType($value);
}
return $value->amount . ' ' . $value->currency;
}
}

Register it for a name with NamedTypeBuilder:

use TypeLang\Mapper\Mapper;
use TypeLang\Mapper\Type\Builder\NamedTypeBuilder;
use TypeLang\Mapper\TypeMatcher\NamedTypePattern;
$mapper = new Mapper(builders: [
new NamedTypeBuilder(new NamedTypePattern(['money']), new MoneyType()),
]);
$mapper->denormalize('100 USD', 'money');
// Money { amount: 100, currency: 'USD' }
$mapper->denormalize(['100 USD'], 'list<money>');
// [Money { amount: 100, currency: 'USD' }]
$mapper->normalize(new Money(100, 'USD'), 'money');
// '100 USD'

A builder creates a type from the parsed type node. Use it for a type with arguments, such as collection<T>.

use TypeLang\Mapper\Context\BuildContext;
use TypeLang\Mapper\Type\Builder\TypeBuilderInterface;
use TypeLang\Mapper\Type\TypeInterface;
use TypeLang\Mapper\TypeMatcher\NamedTypePattern;
use TypeLang\Type\TypeNode;
final class CollectionTypeBuilder implements TypeBuilderInterface
{
private readonly NamedTypePattern $pattern;
public function __construct()
{
$this->pattern = new NamedTypePattern(['collection<T>']);
}
public function tryBuild(TypeNode $node, BuildContext $ctx): ?TypeInterface
{
// ['T' => TypeNode], or null for a node of another form
$arguments = $this->pattern->findArguments($node);
if ($arguments === null) {
return null;
}
// CollectionType is a TypeInterface holding the type of its items
return new CollectionType($ctx->types->getType($arguments['T']));
}
}
$mapper = new Mapper(builders: [new CollectionTypeBuilder()]);
$mapper->denormalize(['1', '2'], 'collection<int>');
// Collection { items: [1, 2] }

An error of an item, wrapped by your type with the key of the item (InvalidValueException::wrapWithPath()), is shown without the expected type: $[1]: Value "x" is invalid. To show it, tell the type of the items with CompositeTypeBuilderInterface:

use TypeLang\Mapper\Type\Builder\CompositeTypeBuilderInterface;
final class CollectionTypeBuilder implements CompositeTypeBuilderInterface
{
// ...
public function tryGetNestedType(TypeNode $node, /* ... */): ?TypeNode
{
return $this->pattern->findArguments($node)['T'] ?? null;
}
}
$mapper->denormalize(['1', 'x'], 'collection<int>');
// throws InvalidValueException:
// $[1]: Value must be of type int, but "x" given