Stars: 136
Forks: 20
Pull Requests: 36
Issues: 24
Watchers: 13
Last Updated: 2023-04-30 09:32:11
JsonDecoder implementation that allows you to convert your JSON data into PHP class objects.
License: Other
Languages: PHP
This package contains a JsonDecoder implementation that allows you to convert your JSON data into php class objects other than stdclass
.
You can install the package via composer
composer require karriere/json-decoder
By default the Decoder will iterate over all JSON fields defined and will try to set this values on the given class type instance. This change in behavior allows the use of json-decoder
on classes that use the magic __get
and __set
functions like Laravel's Eloquent models.
If a property equally named like the JSON field is found or a explicit Binding
is defined for the JSON field it will be decoded into the defined place. Otherwise the property will just be created and assigned (you need the #[AllowDynamicProperties]
attribute if you are on PHP 8.2.).
The JsonDecoder
class can receive one parameter called shouldAutoCase
. If set to true it will try to find the camel-case version from either snake-case or kebap-case automatically if no other binding was registered for the field and it will use an AliasBinding
if one of the variants can be found.
Assume you have a class Person
that looks like this:
#[AllowDynamicProperties]
class Person
{
public int $id;
public string $name;
public ?string $lastname = '';
}
The following code will transform the given JSON data into an instance of Person
.
$jsonDecoder = new JsonDecoder();
$jsonData = '{"id": 1, "name": "John Doe", "lastname": null, "dynamicProperty": "foo"}';
$person = $jsonDecoder->decode($jsonData, Person::class);
Please be aware that since PHP 8.2. dynamic properties are deprecated. So if you still wish to have the ability to make
use of those dynamic properties you have to add the PHP attribute AllowDynamicProperties
to your class.
If you are using PHP 8.2. (and greater) and don't use the AllowDynamicProperties
attribute all dynamic properties will
be ignored.
Let's extend the previous example with a property called address. This address field should contain an instance of Address
.
As of version 4 you can use the introduced method scanAndRegister
to automatically generate the transformer based on class annotations.
Since version 5 you can also make use of the property type instead of a class annotation.
class Person
{
public int $id;
public string $name;
/**
* @var Address
*/
public $address;
public ?Address $typedAddress = null;
}
For this class definition we can decode JSON data as follows:
$jsonDecoder = new JsonDecoder();
$jsonDecoder->scanAndRegister(Person::class);
$jsonData = '{"id": 1, "name": "John Doe", "address": {"street": "Samplestreet", "city": "Samplecity"}, , "typedAddress": {"street": "Samplestreet", "city": "Samplecity"}}';
$person = $jsonDecoder->decode($jsonData, Person::class);
If you don't use annotations or need a more flexible Transformer
you can also create a custom transformer. Let's look at the previous example without annotation.
class Person
{
public int $id;
public string $name;
public mixed $address;
}
To be able to transform the address data into an Address
class object you need to define a transformer for Person
:
The transformer interface defines two methods:
class PersonTransformer implements Transformer
{
public function register(ClassBindings $classBindings)
{
$classBindings->register(new FieldBinding('address', 'address', Address::class));
}
public function transforms()
{
return Person::class;
}
}
After registering the transformer the JsonDecoder
will use the defined transformer:
$jsonDecoder = new JsonDecoder();
$jsonDecoder->register(new PersonTransformer());
$jsonData = '{"id": 1, "name": "John Doe"}';
$person = $jsonDecoder->decode($jsonData, Person::class);
As of version 4 the JsonDecoder
class will handle private
and protected
properties out of the box.
If your JSON contains an array of elements at the root level you can use the decodeMultiple
method to transform the JSON data into an array of class type objects.
$jsonDecoder = new JsonDecoder();
$jsonData = '[{"id": 1, "name": "John Doe"}, {"id": 2, "name": "Jane Doe"}]';
$personArray = $jsonDecoder->decodeMultiple($jsonData, Person::class);
The following Binding
implementations are available
Defines a JSON field to property binding for the given type.
Signature:
new FieldBinding(string $property, ?string $jsonField = null, ?string $type = null, bool $isRequired = false);
This defines a field mapping for the property $property
to a class instance of type $type
with data in $jsonField
.
Defines an array field binding for the given type.
Signature:
new ArrayBinding(string $property, ?string $jsonField = null, ?string $type = null, bool $isRequired = false);
This defines a field mapping for the property $property
to an array of class instance of type $type
with data in $jsonField
.
Defines a JSON field to property binding.
Signature:
new AliasBinding(string $property, ?string $jsonField = null, bool $isRequired = false);
Defines a JSON field to property binding and converts the given string to a DateTime
instance.
Signature:
new DateTimeBinding(string $property, ?string $jsonField = null, bool $isRequired = false, $dateTimeFormat = DateTime::ATOM);
Defines a property binding that gets the callback result set as its value.
Signature:
new CallbackBinding(string $property, private Closure $callback);
Apache License 2.0 Please see LICENSE for more information.