Download the PHP package brick/json-mapper without Composer
On this page you can find all versions of the php package brick/json-mapper. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package json-mapper
Brick\JsonMapper
Maps JSON data to strongly typed PHP DTOs.
Introduction
This library provides an easy-to-use, secure, and powerful way to map JSON data to strongly typed PHP objects.
It reads parameter types & annotations defined on your class constructors to map JSON data to your DTOs, and can work with zero configuration.
Installation
This library is installable via Composer:
Requirements
This library requires PHP 8.1 or later.
Project status & release process
While this library is still under development, it is well tested and considered stable enough to use in production environments.
The current releases are numbered 0.x.y
. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.), y
is incremented.
When a breaking change is introduced, a new 0.x
version cycle is always started.
It is therefore safe to lock your project to a given release cycle, such as 0.1.*
.
If you need to upgrade to a newer release cycle, check the release history for a list of changes introduced by each further 0.x.0
version.
Usage
Basic usage
JsonMapper
provides a single method, map()
, which takes a JSON string and a class name, and returns an instance of the given class.
Nested objects
JsonMapper
will read the parameter types and annotations to map nested objects:
Arrays
Arrays can be documented with @param
annotations, that will be parsed and used to map the JSON data:
Union types
If a parameter is a declared as a union of possible types, JsonMapper
will automatically attempt to map the JSON data to the correct type:
To achieve this, JsonMapper
attempts to map a JSON object to every possible PHP class in the union. If no class matches, or if several classes match, an exception is thrown.
Complex unions
JsonMapper
can parse, map, and verify any combination of possibly nested types:
This currently comes with two limitations:
- you must use the
Type[]
syntax for arrays, and not thearray<Type>
syntax; -
you cannot use more than one array type per union; for example, this is allowed:
but this is not:
Enums
JsonMapper
can map JSON strings and integers to backed enums:
Non-backed enums, i.e. enums that do not have a string
or int
value, are not supported on purpose.
Strictness
The library has very strict defaults (some of which can be overridden by config), and will throw an exception if the JSON data does not exactly match the DTO's constructor signature, or if the DTO contains invalid or unsupported @param
annotations.
The types of the parameters must match exactly, with the same semantics as PHP's strict_types
.
JsonMapper
guarantees that every constructor parameter, even softly-typed with @param
, will be passed a value that is compatible with the declared type. The result is a DTO that can be 100% trusted by your static analysis tool.
Options
The JsonMapper
constructor accepts the following options:
-
$allowUntypedArrays
By default,
JsonMapper
will throw an exception if the parameter is declared asarray
without a corresponding@param
annotation, or is just documented as@param array
.By setting this option to
true
,JsonMapper
will allow such parameters, and accept to pass a JSON array as is, without checking or mapping its contents: -
$allowUntypedObjects
By default,
JsonMapper
will throw an exception if a parameter is declared asobject
orstdClass
.By setting this option to
true
,JsonMapper
will allow such parameters, and accept to pass a JSON object as anstdClass
instance, without checking or mapping its contents: -
$allowMixed
By default,
JsonMapper
will throw an exception if a parameter is declared asmixed
.By setting this option to
true
,JsonMapper
will allow such parameters, and accept to pass a JSON value as is, without checking or mapping its contents: -
$onExtraProperties
This option accepts an
OnExtraProperties
enum value, and controls howJsonMapper
reacts if a JSON object contains a property that does not have a matching parameter in the corresponding DTO's constructor signature:OnExtraProperties::THROW_EXCEPTION
JsonMapper
will throw aJsonMapperException
. This is the default value.OnExtraProperties::IGNORE
JsonMapper
will ignore any extra properties: -
$onMissingProperties
This option accepts an
OnMissingProperties
enum value, and controls howJsonMapper
reacts if a JSON object is missing a property that is declared in the corresponding DTO's constructor signature:OnMissingProperties::THROW_EXCEPTION
JsonMapper
will throw aJsonMapperException
. This is the default value.OnMissingProperties::SET_NULL
JsonMapper
will set the parameter tonull
if the JSON property is missing and the parameter is nullable:If the property is missing and the parameter is not nullable, an exception will be thrown regardless of this option.
OnMissingProperties::SET_DEFAULT
JsonMapper
will set the parameter to its default value if the JSON property is missing and the parameter has a default value:If the property is missing and the parameter does not have a default value, an exception will be thrown regardless of this option.
-
$jsonToPhpNameMapper
&$phpToJsonNameMapper
By default,
JsonMapper
assumes that the JSON property names are the same as the PHP parameter names.By providing implementations of the
NameMapper
interface, you can customize the mapping between the two.The library comes with two implementations for a common use case:
SnakeCaseToCamelCaseMapper
will convertsnake_case
camelCase
CamelCaseToSnakeCaseMapper
will convertcamelCase
tosnake_case
Example: