Skip to content

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:

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.

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(),
);
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.

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-string

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