Overview
Comparison
The same classes and the same arrays are given to every tool, the tables list what comes back.
| Tool | Version | Types are read from |
|---|---|---|
| TypeLang | type-lang/mapper 2.0 |
native types, docblocks, attributes |
| Valinor | cuyz/valinor 2.8 |
native types, docblocks |
| Symfony | symfony/serializer 8.1 |
native types, docblocks (PropertyInfo) |
| JMS | jms/serializer 3.32 |
native types, docblocks (enabled), attributes |
Every tool maps an array to an object, no format is involved. The settings are the default ones, the options a table depends on are named next to it.
A property is declared with the type, then a matching and a non-matching value are mapped to it.
| Sign | Meaning |
|---|---|
| ✓ | the matching value is accepted, the other is rejected |
| ! | the declaration is read, the non-matching value passes |
| ✗ | the declaration is rejected |
| Type | TypeLang | Valinor | Symfony | JMS |
|---|---|---|---|---|
int, ?int, Inner |
✓ | ✓ | ✓ | ✓ |
BackedEnum |
✓ | ✓ | ✓ | ✓ |
DateTimeImmutable |
✓ | ✓ | ✓ | ✓ |
int[], array<string, int> |
✓ | ✓ | ✓ | ✓ |
list<Inner> |
✓ | ✓ | ✓ | ✓ |
int|bool |
✓ | ✓ | ✓ | ! |
list<int> |
✓ | ✓ | ! | ! |
non-empty-string |
✓ | ✓ | ! | ! |
numeric-string |
✓ | ✓ | ! | ! |
positive-int |
✓ | ✓ | ! | ! |
int<1, 10> |
✓ | ✓ | ! | ! |
'a'|'b' |
✓ | ✓ | ! | ! |
1|2|3 |
✓ | ✓ | ! | ! |
value-of<Suit> |
✓ | ✓ | ! | ! |
Example::CONST_* |
✓ | ✓ | ! | ! |
non-empty-list<int> |
✓ | ✓ | ! | ✗ |
array{id: int, name?: string} |
✓ | ✓ | ! | ✗ |
int-mask<1, 2, 4> |
✓ | ✗ | ! | ! |
final class Example{ /** * @var list<int> */ public array $value;}
// ['value' => ['a' => 1]]//// TypeLang: $.value: Value must be of type list<int>, but array(1) given// Valinor: value.a: Invalid sequential key 'a'// Symfony: ['a' => 1]// JMS: [1]Coercion
Section titled “Coercion”A value of another scalar type is mapped to a property of the type. Every tool has a strict mode and a converting one, the default differs:
| Tool | Strict | Converting |
|---|---|---|
| TypeLang | new Configuration(strict: true) |
default |
| Valinor | default | allowScalarValueCasting() |
| Symfony | default | enable_type_conversion 1, disable_type_enforcement 2 |
| JMS | new JsonDeserializationVisitorFactory(true) |
default |
In the strict mode every tool rejects every value below. An int as a
float is the exception: TypeLang and Valinor accept 42 as 42.0.
In the converting mode:
| Value to type | TypeLang | Valinor | Symfony 1 | Symfony 2 | JMS |
|---|---|---|---|---|---|
'42' to int |
42 |
42 |
42 |
42 |
42 |
42.0 to int |
42 |
42 |
rejected | 42 |
42 |
' 42' to int |
rejected | 42 |
rejected | 42 |
42 |
42.5 to int |
rejected | rejected | rejected | 42 |
42 |
'1e3' to int |
rejected | rejected | rejected | 1000 |
1000 |
true to int |
rejected | rejected | rejected | 1 |
1 |
'abc' to int |
rejected | rejected | rejected | rejected | 0 |
'4.5' to float |
4.5 |
4.5 |
4.5 |
4.5 |
4.5 |
true to float |
rejected | rejected | rejected | 1.0 |
1.0 |
42 to string |
'42' |
'42' |
rejected | '42' |
'42' |
true to string |
rejected | rejected | rejected | '1' |
'1' |
'true' to bool |
true |
true |
true |
true |
true |
1 to bool |
true |
true |
rejected | true |
true |
'yes' to bool |
true |
rejected | rejected | true |
true |
2 to bool |
rejected | rejected | rejected | true |
true |
'abc' to bool |
rejected | rejected | rejected | true |
true |
enable_type_conversionconverts strings only, it is the default of the XML and CSV formats. Thefilter_booloption adds1and'yes'asbool.disable_type_enforcementskips the type check, the value is converted by PHP on assignment.
TypeLang converts a value only when it is the same value written in another form, see type coercion.
Invalid data
Section titled “Invalid data”Each table gives the default behaviour and the option that changes it, a dash stands where no option was found.
Unknown field
Section titled “Unknown field”The data has a field that no property of the class takes.
| Tool | Default | Option |
|---|---|---|
| TypeLang | ignored | rejected by rejectExtraFields: true, kept by ... of a shape |
| Valinor | rejected | ignored by allowSuperfluousKeys() |
| Symfony | ignored | rejected by allow_extra_attributes: false |
| JMS | ignored | — |
Missing field
Section titled “Missing field”The data has no field for a property without a default value.
| Tool | Default | Option |
|---|---|---|
| TypeLang | rejected | — |
| Valinor | rejected | null for a nullable one by allowUndefinedValues() |
| Symfony | property is left uninitialized | — |
| JMS | property is left uninitialized | — |
An uninitialized property is returned inside the object, reading it throws
an Error.
Errors
Section titled “Errors”Two properties of an object and of its nested object get wrong values.
| Tool | Default | Option | Path |
|---|---|---|---|
| TypeLang | the first error | all by maxViolations |
$.b.id |
| Valinor | all errors | — | b.id |
| Symfony | the first error | all by collect_denormalization_errors: true |
b.id |
| JMS | no error | the first one in the strict mode | — |
JMS reports no error by default: a wrong scalar value is converted.
Performance
Section titled “Performance”One instance of the tool converts the same value again and again. The time is of one call, lower is better, the factor is relative to TypeLang.
| Scenario | TypeLang | JMS | Valinor | Symfony |
|---|---|---|---|---|
| Denormalize an object | 1.4 µs | 6.4 µs (×4.5) | 19.1 µs (×13) | 40.0 µs (×28) |
| Denormalize 100 objects | 130 µs | 361 µs (×2.8) | 1 863 µs (×14) | 4 129 µs (×32) |
| Normalize an object | 1.0 µs | 10.1 µs (×10) | 7.6 µs (×7.8) | 16.4 µs (×17) |
| Normalize 100 objects | 81 µs | 669 µs (×8.2) | 744 µs (×9.1) | 1 664 µs (×20) |
With a persistent metadata cache, the production setup of every tool:
| Scenario | TypeLang | JMS | Valinor | Symfony |
|---|---|---|---|---|
| Denormalize an object | 1.4 µs | 6.6 µs (×4.7) | 19.3 µs (×14) | 39.9 µs (×28) |
| Denormalize 100 objects | 130 µs | 399 µs (×3.1) | 1 842 µs (×14) | 4 187 µs (×32) |
| Normalize an object | 1.0 µs | 10.2 µs (×10) | 1.7 µs (×1.7) | 16.6 µs (×17) |
| Normalize 100 objects | 82 µs | 702 µs (×8.5) | 105 µs (×1.3) | 1 673 µs (×20) |
The object has five scalar properties and a nested object of two. PHP 8.4.13 with OPcache and the tracing JIT, Windows 11, measured by PHPBench. Every tool is checked to return the same result before it is measured.
The benchmarks are in the bench/Mapper/Tools directory of the monorepo:
vendor/bin/phpbench run bench/Mapper/Tools --report=compare