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'$mapper->denormalize('ten dollars', 'money');// throws InvalidValueException:// $: Value must be of type money, but "ten dollars" givenType builders
Section titled “Type builders”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] }Errors of nested values
Section titled “Errors of nested values”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