Metadata
Metadata
Metadata describes how a class is mapped: which properties, of which types, under which names. Without any metadata the mapper uses the class as it is:
- only public non-static properties are mapped, inherited ones too;
- the type of a property is its native type, a property without a type is an error;
- a property with a default value is optional;
- an object is created without calling the constructor.
use TypeLang\Mapper\Mapper;
final class User{ public int $id; public string $role = 'user'; private bool $isAdmin = false;}
$mapper = new Mapper();
$user = $mapper->denormalize(['id' => 1, 'isAdmin' => true], User::class);// User { id: 1, role: 'user', isAdmin: false }
$mapper->normalize($user);// ['id' => 1, 'role' => 'user']Everything else is described with metadata:
- Property Types — the type of a property, read and write types, strictness
- Naming — field names, aliases and naming strategies
- Discriminator Map — choosing a class by a field of the data
- Error Messages — custom messages of errors
- Skipping Properties — leaving properties out of the normalized data
- Getters and Setters — methods and hooks a property is accessed through, one direction only
- Miscellaneous — objects as arrays, default values, enum value aliases
Sources
Section titled “Sources”| Source | Example | Requires |
|---|---|---|
| Attributes | #[MapType('list<string>')] |
|
| PHPDoc | @var list<string> |
type-lang/phpdoc |
| Reflection | public array $tags |
|
| PHP Config | return ['App\User' => [...]]; |
|
| JSON Config | {"App\\User": {...}} |
|
| YAML Config | App\User: ... |
symfony/yaml |
| NEON Config | App\User: ... |
nette/neon |
Attributes, PHPDoc and reflection are enabled by default, config files are enabled explicitly. Priority, from the highest: attributes, PHPDoc, reflection.
Readers
Section titled “Readers”The metadata provider is built by MetadataBuilder. A reader of a
higher priority overrides the values of a lower one, of readers with an
equal priority the later added one wins. Reflection is always the lowest.
The getters and setters of attributes and
configs are read right above it, so every reader reads the types at them.
use TypeLang\Mapper\Mapper;use TypeLang\Mapper\Mapping\MetadataBuilder;
// attributes (300), PHPDoc @type-lang-var (200), PHPDoc @var (100), reflection$builder = MetadataBuilder::createDefault();
// reflection only$builder = new MetadataBuilder();
$mapper = new Mapper( metadata: (new MetadataBuilder()) ->withPhpDocReader(priority: 10) ->withAttributeReader(priority: 20) ->withAddedReader(new MyReader(), priority: 30) ->build(),);| Method | Reader |
|---|---|
withAttributeReader() |
attributes |
withPhpDocReader() |
PHPDoc tags |
withYamlReader() |
YAML config |
withNeonReader() |
NEON config |
withJsonReader() |
JSON config |
withPhpReader() |
PHP config |
withAddedReader() |
any MetadataReaderInterface |
withReflectionReader() |
replaces the selector of the properties |
The type parser of the readers and the expression language of the attributes are passed once:
new MetadataBuilder( parser: new TypeParser(), expressions: new ExpressionLanguage(),);PHPDoc tags
Section titled “PHPDoc tags”use TypeLang\Mapper\Mapping\Reader\PhpDocMetadataReader\MapperPlatform;
$builder = MetadataBuilder::createDefault() // @api-var of a property, @api-param of a set hook, // @api-return of a get hook ->withPhpDocReader(new MapperPlatform( var: 'api-var', varAliases: ['api-type'], return: 'api-return', returnAliases: [], param: 'api-param', paramAliases: [], ), priority: 250);The default tags (MapperPlatform::createWithDefaultTagNames()) are @var,
@param, @return and their @phpstan-*, @psalm-* and @phan-* aliases.
Config files
Section titled “Config files”A config file is a map of classes to their metadata:
use TypeLang\Mapper\Mapper;use TypeLang\Mapper\Mapping\MetadataBuilder;
$mapper = new Mapper( metadata: MetadataBuilder::createDefault() ->withYamlReader(__DIR__ . '/mapping.yaml', priority: 400) ->build(),);| Format | Method | Requires |
|---|---|---|
| PHP | withPhpReader() |
|
| JSON | withJsonReader() |
|
| YAML | withYamlReader() |
symfony/yaml |
| NEON | withNeonReader() |
nette/neon |
An array is read by withAddedReader(new ArrayMetadataReader([...])).
App\User: normalize_as_array: true properties: id: positive-int email: name: e_mail type: non-empty-stringCaching
Section titled “Caching”Reading metadata (especially PHPDoc) is slow. Add PSR-6 or PSR-16 caches, from the first one checked to the last one:
use TypeLang\Mapper\Mapper;use TypeLang\Mapper\Mapping\MetadataBuilder;
$mapper = new Mapper( metadata: MetadataBuilder::createDefault() ->withPsr16Cache($redis, prefix: 'hot_') ->withPsr6Cache($files, prefix: 'cold_') ->build(),);// a miss of Redis reads the files and stores the metadata in Redis