Download the PHP package square/pjson without Composer

A simple library for JSON to PHP Objects conversions

Often times, we interact with an API, or data source that returns JSON. PHP only offers the possibility to deserialize that json into an array or objects of type stdClass.

This library helps deserializing JSON into actual objects of custom defined classes. It does so by using PHP8's attributes on class properties.

Examples

Simple serialization of a class

Would yield the following:

And then the reverse can be achieved via:

Which would return an instance of class Schedule with the properties set according to the JSON.

Custom Names

The previous example can be made to use custom names in JSON instead of just the property name:

would yield

And deserializing with those new property names works just as before:

Private / Protected

The visibility of a property does not matter. A private or protected property can be serialized / unserialized as well (see previous examples).

Property Path

Sometimes the json format isn't exactly the PHP version we want to use. Say for example that the JSON we received for the previous schedule examples were to look like:

By declaring our class json attributes as follows, we can still read those properties direclty into our class:

Recursive serialize / deserialize

If we are working with a json structure that's a bit more complex, we will want to have properties be classes that can also be properly deserialized into.

The following 2 PHP classes could work well with this:

Arrays

When working with an array of items where each item should be of a given class, we need to tell pjson about the target type:

With Schedule still defined as before, we'd define a week like:

This would also work with a map if the json were like:

And the resulting PHP object would be:

Collection Classes

Similar to arrays, you might want to use collection classes. You can do so as long as your classes implement the Traversable interface. In this case, pjson will by default try to construct your class by passing in the array of data in the constructor. If this doesn't work for you, you can specify a custom factory method for your collections:

Here our collection has a static factory method make and an instance method makeme that could each be used. The constructor option also works. You can look at the collection class in the tests/Definitions directory.

This would allow you to work with json like:

Polymorphic deserialization

Say you have 2 classes that extend a base class. You might receive those as part of a collection and don't know ahead of time if you'll be dealing with one or the other. For example:

You can implement the fromJsonData(array $array) : static on CatalogObject to discriminate based on the received data and return the correct serialization:

WARNING: Make sure that each of the subclasses directly use JsonSerialize. Otherwise when they call ::fromJsonData, they would call the parent on CatalogObject leading to infinite recursion.

With this in place, we can do:

Lists

If you're dealing with a list of things to deserialize, you can call MyClass::listFromJsonString($json) or MyClass::listfromJsonData($array). For example:

yields the same as

Initial path

Somteimes the JSON you care about will be nested under a property but you don't want / need to model the outer layer. For this you can pass a $path to the deserializing methods:

Enums

Backed enums are supported out of the box in PHP 8.1

And regular enums can be supported via the JsonSerialize trait or the JsonDataSerializable interface

Required properties

You can mark a property as required for deserialization:

Scalar <=> Class

In some cases, you might want a scalar value to become a PHP object once deserialized and vice-versa. For example, a BigInt class could hold an int as a string and represent it as a string when serialized to JSON:

Collection Classes

If you wish to use pjson with collection classes

Use with PHPStan

Using this library, you may have properties that don't appear to be read from or written to anywhere in your code, but are purely used for JSON serialization. PHPStan will complain about these issues, but you can help PHPStan understand that this is expected behavior by adding this library's extension in your phpstan.neon.

Laravel Integration

via castable

If you wish to cast Eloquent model attributes to classes via Pjson, you might do so with the provided casting utilities:

Then in your Eloquent model:

via cast arguments

Alternatively, you can simply use Laravel's cast arguments. In this case the Schedule class stays the way it used to be:

And you provide the class target of the cast like: