Metadata
Property types
The type of a property and its strictness.
Every option is shown in each metadata source: choose the tab of the source you use. When a source cannot express an option, its tab says what is used instead.
The type of the property: any supported type. When it is not specified, the native type of the property is used.
use TypeLang\Mapper\Mapping\MapType;
final class User{ #[MapType('list<non-empty-string>')] public array $tags = [];}final class User{ /** * @var list<non-empty-string> */ public array $tags = [];
/** * @param list<non-empty-string> $roles */ public function __construct( public array $roles = [], ) {}}final class User{ public array $tags = [];}<?php
return [ App\User::class => [ 'properties' => [ 'tags' => 'list<non-empty-string>', ], ],];{ "App\\User": { "properties": { "tags": "list<non-empty-string>" } }}App\User: properties: tags: list<non-empty-string>App\User: properties: tags: list<non-empty-string>$mapper->denormalize(['tags' => ['php', 'mapper']], User::class);// User { tags: ['php', 'mapper'] }$mapper->denormalize(['tags' => ['php', '']], User::class);// throws InvalidValueException:// $.tags[1]: Value must be of type non-empty-string (non-empty)Read and write types
Section titled “Read and write types”Different types for normalization (read) and denormalization (write), given
on the get and set hooks of a property (PHP 8.4):
- attributes: a type on the property itself sets both types;
- PHPDoc: the tags of the hooks, then
@var, which sets only the read type when thesethook takes another type; - reflection: the read type is the declared type of the property, the write
type is the parameter type of the
sethook; - config:
read_typeorwrite_typeof a direction the property does not take part in, such aswrite_typewithout asethook, is an error.
use TypeLang\Mapper\Mapping\MapType;
final class User{ private string $value = '';
public mixed $id { #[MapType('int')] get => (int) $this->value; #[MapType('positive-int')] set(mixed $id) { $this->value = (string) $id; } }}final class User{ private string $value = '';
public mixed $id { /** @return int */ get => (int) $this->value; /** @param positive-int $id */ set(mixed $id) { $this->value = (string) $id; } }}final class User{ private string $value = '';
public int $id { get => (int) $this->value; set(int|string $id) { $this->value = (string) $id; } }}<?php
return [ App\User::class => [ 'properties' => [ 'id' => [ 'read_type' => 'int', 'write_type' => 'positive-int', ], ], ],];{ "App\\User": { "properties": { "id": { "read_type": "int", "write_type": "positive-int" } } }}App\User: properties: id: read_type: int write_type: positive-intApp\User: properties: id: read_type: int write_type: positive-int$user = $mapper->denormalize(['id' => '42'], User::class);$user->id; // 42$mapper->normalize($user); // ['id' => 42]$mapper->denormalize(['id' => -1], User::class);// throws InvalidValueException:// $.id: Value must be of type positive-int (>= 1)Strict types
Section titled “Strict types”Disables type coercion for the value of the property
and its nested values, or enables it with false. Overrides the
configuration option.
use TypeLang\Mapper\Mapping\MapType;
final class User{ #[MapType('int', strict: true)] public int $id;}<?php
return [ App\User::class => [ 'properties' => [ 'id' => [ 'type' => 'int', 'strict' => true, ], ], ],];{ "App\\User": { "properties": { "id": { "type": "int", "strict": true } } }}App\User: properties: id: type: int strict: trueApp\User: properties: id: type: int strict: true$mapper->denormalize(['id' => 42], User::class); // User { id: 42 }$mapper->denormalize(['id' => '42'], User::class);// throws InvalidValueException:// $.id: Value must be of type int, but "42" given