Extending
Formatters
A formatter writes the text of one violation. The mapper builds the message
of an InvalidValueException from it: the path of the first violation, its
text and the number of the others.
$.status: Value must be of type 'new'|'paid', but "x" given (and 1 more)└──┬───┘ └─────────────────────┬─────────────────────────┘ └────┬─────┘ path text of the formatter mapperThe mapper has one formatter per direction, they write for different readers:
| Argument | Reader | Default | Type in the text | Value in the text |
|---|---|---|---|---|
denormalizationFormatter |
a client sending the data | PublicViolationFormatter |
expected: 'new'|'paid' |
public: "x", object |
normalizationFormatter |
a developer of the application | ViolationFormatter |
declared: App\Status |
short: "x", object(App\User) |
The expected type and the declared type are described in
errors. In an application a formatter is set by
the formatters config key of Symfony
and Laravel.
Templates
Section titled “Templates”The text is the template of the violation with its placeholders replaced. The template is the one set by metadata, or the one of the code of the violation.
| Placeholder | Value |
|---|---|
{{expected}} |
the type, printed by the type printer |
{{value}} |
the rejected value, printed by the value printer |
{{field}} |
the name of the missing, unexpected or duplicate field |
{{other}} |
the field a duplicate field repeats |
{{check}} |
the failed check of a refined type, such as positive-int |
A code that names the type has a second template without it, used when the
type is unknown: Value {{value}} is invalid. In a template of metadata an
unknown type and a check of a violation of another kind are empty.
Built-in formatters
Section titled “Built-in formatters”use TypeLang\Mapper\Diagnostics\Printer\Value\PublicValuePrinter;use TypeLang\Mapper\Diagnostics\Printer\Value\ShortValuePrinter;use TypeLang\Mapper\Diagnostics\PublicViolationFormatter;use TypeLang\Mapper\Diagnostics\ViolationFormatter;use TypeLang\Mapper\Mapper;use TypeLang\Printer\PrettyTypePrinter;use TypeLang\Printer\PrinterOptions;
// the type printer of the mapper: shapes in one line with all fields$types = new PrettyTypePrinter( new PrinterOptions(maxInlineShapeFields: \PHP_INT_MAX),);
$mapper = new Mapper( // the expected type, the value printed by PublicValuePrinter denormalizationFormatter: new PublicViolationFormatter($types),
// the declared type, the value printed by ShortValuePrinter normalizationFormatter: new ViolationFormatter( valuePrinter: new ShortValuePrinter(), typePrinter: $types, shouldPrintDeclaredType: true, ),);ViolationFormatter with shouldPrintDeclaredType: false prints the
expected type, the way PublicViolationFormatter does.
Value printers
Section titled “Value printers”| Printer | Prints |
|---|---|
ShortValuePrinter |
scalars by value, a string cut to maxStringLength characters (40), arrays and objects by kind: array(3), object(App\User) |
PublicValuePrinter |
an object as object, a case of an enum as its value or name, the rest by the inner printer (ShortValuePrinter) |
A string of the data may be a password or a token. To keep it out of the messages sent to clients, print strings by their length only:
$mapper = new Mapper( denormalizationFormatter: new PublicViolationFormatter( $types, new PublicValuePrinter(new ShortValuePrinter(maxStringLength: 0)), ),);
$mapper->denormalize('abcdef', 'int');// throws InvalidValueException:// $: Value must be of type int, but string(6) givenCustom formatter
Section titled “Custom formatter”A formatter implements ViolationFormatterInterface. The violation gives
everything the text is made of: the code, the parameters of the
placeholders, the path, the rejected value, the expected and
declared types and the template of metadata.
A formatter translating the templates by the code, the placeholders are still replaced by the built-in formatter:
use TypeLang\Mapper\Diagnostics\PublicViolationFormatter;use TypeLang\Mapper\Diagnostics\Violation;use TypeLang\Mapper\Diagnostics\ViolationFormatterInterface;use TypeLang\Mapper\Mapper;
final class TranslatedFormatter implements ViolationFormatterInterface{ private const array TEMPLATES = [ 'invalid_type' => 'Erwartet {{expected}}, erhalten {{value}}', 'missing_field' => 'Pflichtfeld "{{field}}" fehlt', ];
public function __construct( private ViolationFormatterInterface $formatter, ) {}
public function format(Violation $violation): string { $template = self::TEMPLATES[$violation->code->getCode()] ?? null;
// a template set by metadata is kept as is if ($template !== null && $violation->template === null) { $violation = $violation->withTemplate($template); }
return $this->formatter->format($violation); }}
$mapper = new Mapper( denormalizationFormatter: new TranslatedFormatter( new PublicViolationFormatter($types), ),);
$mapper->denormalize('x', 'int');// throws InvalidValueException: $: Erwartet int, erhalten "x"