Download the PHP package dschledermann/json-coder without Composer

JSON Coder

This package can encode and decode JSON to and from PHP classes. It is useful for packing DTOs on queues, for cloud storage or just for HTTP-replies. Reflection is used, and any constructor logic is surpassed. The decoder is quite happy to ignore extra fields that may be in a payload, so you can grab just the field your application uses.

Installation

Usage

Instantiate the Coder and configure it if you need to.

Encoding

This is very straight forward:

Example:

This will output:

Decoding

Here you need to specify what class you wish to decode into. Apart from this, it is basically the reverse:

This will output something like:

Configure the Coder

If you have some more advanced needs, then it's possible to pass options to the and functions.

If need to change the style of the keys, then that's also possible. This is useful when interfacing with API's or languages where the naming convention differs from PHP's.

Outputs:

Using snake case:

Outputs:

The same "direction" of the key case converter is used both for encoding and decoding JSON, so you don't have to configure the Coder in a different way depending on use.

See the test suite for more examples.

If you need something else, then make a class where you implement the KeyConverterInterface and make it an Attribute.

Using the "Choice"

In many cases you can expect multiple variants on an API reply or AMQP queue. Fortunately this packages also gives a convenient way to handle that. This package has the VariantChoiceTrait that will make it easier for you to define an umbrella for all the types you expected to receive.

The assumption is that you only have one toplevel key, and that key defines what variant you are dealing with.

There are some limitations on this:

1. Each key has to be of a unique type.
2. You should not have any additional properties on the payload choice class.
3. Check for null output. Decoding and encoding is done with soft reflection "magic". If there are no matches, you will receive a null value.

Consider that you have these two choices:

A person:

Or a car:

You can now create a payload class that has each as a variant:

Consider this payload:

This PHP-code will decode it:

Will output something like this:

The variable $listOfChoices will now contain Payload objects. Each of them can be queried what variant they using the VariantChoiceTrait::getVariantType() method.

Encoding a choice

It's also useful to be able to wrap a variant object in the choice container. Consider this code:

This will output something like:

And if you encode it, the result will be this:

It's a very good idea to mark the top level choice class with the SkipEncodeIfNull-attribute. If not, then all the empty variants will be present with a null value, which is almost certainly not what you want.

Decoding nested structures

Nested arrays present a challenge in PHP as the array declaration does not contain limitations on the types in the array. There are a couple of conventions to work around this. The commonly used is a docblock comment indicating the array shape. The two formats supported in this package are "T[]" and "array".

We can decode this JSON, and it will enforce that all the elements are indeed integers.

The code will throw an exception if an element in the list is not an int.

We can also coerce a substructure into a complex type:

This JSON can be decoded, and the elements in $subTypeList will all be of class "SubType".

Into something like this:

This works for simple, native types and for types within the same namespace. If you are using types from other namespaces, you have two options:

• Use the full path of the class in the type hinting
• Use the ListType as an attribute to indicate.

Using attribute:

Using full path type hinting:

Dealing with array indexes

When encoding or decoding structures, sometimes it's required to keep the indexes, and other places they should be discarded. This can matter because JSON distinguishes between maps and lists. You can control the behaviour of this using the "SquashIndexes" attribute.

Consider this:

If you have this array:

$json will now contain this string:

If you wish to discard the indexes to get a proper array, use the "SquashIndexes"-attribute:

And now you will get:

You can also use the attribute on lists inside a class. Example:

Here, $json will keep the indexes in the inner list:

Adding the "SquashIndexes"-attribute:

... and you will get this JSON instead: