Skip to content

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 supported

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" given

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
}

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" given

The 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.