Types
Errors
| Exception | When |
|---|---|
InvalidValueException |
the data does not match the type |
TypeDefinitionException |
the type is unknown, written or declared wrong |
Both are in the TypeLang\Mapper\Exception namespace and implement
MapperExceptionInterface.
final class User{ public int $id;}
$mapper->denormalize(['id' => 'abc'], User::class);// throws InvalidValueException:// $.id: Value must be of type int, but "abc" given
$mapper->denormalize([], 'list<int');// throws TypeDefinitionException:// Type "list<int" is written wrong:// Invalid template arguments, "," or ">" is expected
$mapper->denormalize([], 'unknown');// throws TypeDefinitionException: Type "unknown" is not supportedViolations
Section titled “Violations”An InvalidValueException contains a list of violations. Each one has a
code, a path, the rejected value, the expected type and the parameters of its
message.
use TypeLang\Mapper\Exception\InvalidValueException;
try { $mapper->denormalize(['id' => 'abc'], User::class);} catch (InvalidValueException $e) { $violation = $e->violations[0];
$violation->code; // ViolationCode::InvalidType $violation->value; // 'abc' $violation->declared; // TypeNode of `int` $violation->expected; // TypeNode of `int` $violation->cause; // null, or the exception of a hook}The declared type is the type of the value as it is declared: by a property
or by the type given to the mapper. It is null when the declaration is not
known, such as for a generic type of your own. The expected type is the
declared one shown to a client: without the classes, enums and constants of
the application (see messages).
| Code | Message |
|---|---|
invalid_type |
Value must be of type {{expected}}, but {{value}} given, Value {{value}} is invalid without the expected type |
invalid_key |
Key must be of type {{expected}}, but {{value}} given, Key {{value}} is invalid without the expected type |
missing_field |
Required field "{{field}}" is missing |
unexpected_field |
Unexpected field "{{field}}" |
duplicate_field |
Field "{{field}}" duplicates the field "{{other}}", a property is given by its name and by an alias |
failed_check |
Value must be of type {{expected}} ({{check}}), Value {{value}} is invalid ({{check}}) without the expected type |
invalid_value |
Value {{value}} is rejected: an exception of a hook, or of a custom type nested in a list, an array, a shape or a class. Its message is not shown, the exception is $violation->cause and $e->getPrevious() |
The path of a violation is printed as JSONPath. Properties renamed by metadata have the names of the data.
$mapper->denormalize(['items' => [['id' => 1], ['id' => 'x']]], Order::class);// throws InvalidValueException:// $.items[1].id: Value must be of type int, but "x" givenCollecting violations
Section titled “Collecting violations”By default the first violation fails. To collect several of them, use the max violations option.
final class User{ public int $id; public string $name;}
use TypeLang\Mapper\Configuration;use TypeLang\Mapper\Exception\InvalidValueException;use TypeLang\Mapper\Mapper;
$mapper = new Mapper(new Configuration(maxViolations: 100));
try { $mapper->denormalize(['id' => 'abc'], User::class);} catch (InvalidValueException $e) { $e->getMessage(); // '$.id: Value must be of type int, but "abc" given (and 1 more)'
\count($e->violations); // 2}Messages
Section titled “Messages”Every message is formatted by the template of the code. Custom templates are set by metadata.
The message of the exception is safe to return to clients: the classes, enums and constants of the application are replaced by the data they take, the messages of the exceptions of hooks are not shown.
enum Status: string{ case New = 'new'; case Paid = 'paid';}
final class Address{ public string $city;}
final class Order{ public Status $status; public ?Address $address;}
$mapper->denormalize(['status' => 'x'], Order::class);// throws InvalidValueException:// $.status: Value must be of type 'new'|'paid', but "x" given
$mapper->denormalize(['status' => 'new', 'address' => 42], Order::class);// throws InvalidValueException:// $.address: Value must be of type ?object{city: string}, but 42 given| Declared type | In the message |
|---|---|
| class | object, its fields with the expected type depth: object{name: string} |
| interface, discriminator | object |
| backed enum | values of the cases: 'new'|'paid' |
| unit enum | names of the cases: 'Hearts'|'Spades' |
| date | string |
constant, mask of constants, value-of<T> |
their values: 200|201 |
| other types | as written: list<'new'|'paid'>, non-empty-string |
An error of normalization is an error of the values of the application, its message is written for a developer: with the declared type.
$mapper->normalize('active', Status::class);// throws InvalidValueException:// $: Value must be of type App\Status, but "active" givenThe text of a message is written by the formatter of its direction, see formatters. How a type of your own is shown to clients is decided by expanders.
The message of the exception shows the first violation only. To list all
the errors in an API response, or to write them with the classes for a log,
format the violations yourself: $violation->expected is the type for a
client, $violation->declared the type with the classes.
use TypeLang\Mapper\Configuration;use TypeLang\Mapper\Diagnostics\Printer\Path\JsonPathPrinter;use TypeLang\Mapper\Diagnostics\PublicViolationFormatter;use TypeLang\Mapper\Exception\InvalidValueException;use TypeLang\Mapper\Mapper;use TypeLang\Printer\PrettyTypePrinter;
$mapper = new Mapper(new Configuration(maxViolations: 100));
$paths = new JsonPathPrinter();$formatter = new PublicViolationFormatter(new PrettyTypePrinter());
try { $mapper->denormalize(['status' => 'x', 'address' => 42], Order::class);} catch (InvalidValueException $e) { $errors = [];
foreach ($e->violations as $violation) { $path = $paths->print($violation->path); $errors[$path] = $formatter->format($violation); }}
// [// '$.status' => 'Value must be of type \'new\'|\'paid\', but "x" given',// '$.address' => 'Value must be of type ?object{city: string}, ...',// ]For a log, ViolationFormatter writes the same messages with the declared
types: Value must be of type \App\Status, but "x" given.