How to Use the JsonSerializable Interface

Over the past few years JSON has taken over as the king of data interchange formats. Before JSON, XML ruled the roost. It was great at modeling complex data but it is difficult to parse and is very verbose. JSON really took off with the proliferation of rich AJAX driven sites as it’s a very human readable format, quick to parse and its simple key/value representation cuts out all the verbosity of XML.

I think we could all agree that writing less code that in turn requires less maintenance and introduces less bugs is a goal we would all like to achieve. In this post, I’d like to introduce you to a little known interface that was introduced in PHP 5.4.0 called JsonSerializable.

Before the JsonSerializable interface was available, returning a JSON encoded representation of an object for a consuming service meant one of two things.

Key Takeaways

• The JsonSerializable interface in PHP 5.4.0 offers a more efficient way to return a JSON encoded representation of an object, eliminating the need to construct a data structure outside the object or to internalize the encoding functionality within the object.
• The JsonSerializable interface allows for the implementation of a jsonSerialize method within the class, which is automatically triggered when an instance of the class is json encoded. This method returns an array of the object data, simplifying the process of updating the data if changes are required.
• Implementing the JsonSerializable interface enhances code maintainability and reduces chances of introducing bugs, as it removes duplication and makes it easier for others to test the object’s ability to be encoded by checking if it’s an instance of JsonSerializable.

The Ugly

The first approach was to construct a data structure outside the object that contained all the data that we wanted to expose.

<span><span><?php </span></span><span>
</span><span><span>class Customer
</span></span><span><span>{
</span></span><span>
</span><span>    <span>private $email = null;
</span></span><span>    <span>private $name = null;
</span></span><span>
</span><span>    <span>public function __construct($email, $name)
</span></span><span>    <span>{
</span></span><span>        <span>$this->email = $email;
</span></span><span>        <span>$this->name = $name;
</span></span><span>    <span>}
</span></span><span>
</span><span>    <span>public function getName()
</span></span><span>    <span>{
</span></span><span>        <span>return $this->name;
</span></span><span>    <span>}
</span></span><span>
</span><span>    <span>public function getEmail()
</span></span><span>    <span>{
</span></span><span>        <span>return $this->email;
</span></span><span>    <span>}
</span></span><span><span>}
</span></span><span>
</span><span><span>$customer = new Customer('customer@sitepoint.com', 'Joe');
</span></span><span>
</span><span><span>$data = [
</span></span><span>    <span>'customer' => [
</span></span><span>        <span>'email' => $customer->getEmail(),
</span></span><span>        <span>'name' => $customer->getName()
</span></span><span>    <span>]
</span></span><span><span>];
</span></span><span>
</span><span><span>echo json_encode($data);</span></span></span>

We used an array here to hold the data from the Customer object that we wanted to encode, but it could just as easily have been an StdClass.

This approach was flexible and served its purpose in very simple situations where we knew that the Customer object wasn’t going to change and we were only going to need Customer data in this format, in this one place. We also had the option of adding data to this array from other sources if we needed to.

However as we’ve all experienced at one time or another, the assumptions we’ve made can be proven false at a moments notice. We might get a requirement that asks us to add more data to the Customer class. That new data will need to be returned to the consuming service and we’ll want to do this in numerous places.

As you can imagine, this approach quickly becomes troublesome. Not only do we have to duplicate this array code all over our application, we have to remember to update all those instances when more changes inevitably come in. There is another way though, that will help us nullify some of these issues.

The Bad

Luckily we were smart when the first change request came in and we realized that duplicating our array was going to be a nightmare, so what we decided to do was internalize that encoding functionality in our object, removing the maintenance issues and reducing the likelihood of introducing bugs.

<span><span><?php </span></span><span>
</span><span><span>class Customer
</span></span><span><span>{
</span></span><span>
</span><span>    <span>private $email = null;
</span></span><span>    <span>private $name = null;
</span></span><span>
</span><span>    <span>public function __construct($email, $name)
</span></span><span>    <span>{
</span></span><span>        <span>$this->email = $email;
</span></span><span>        <span>$this->name = $name;
</span></span><span>    <span>}
</span></span><span>
</span><span>    <span>public function getName()
</span></span><span>    <span>{
</span></span><span>        <span>return $this->name;
</span></span><span>    <span>}
</span></span><span>
</span><span>    <span>public function getEmail()
</span></span><span>    <span>{
</span></span><span>        <span>return $this->email;
</span></span><span>    <span>}
</span></span><span><span>}
</span></span><span>
</span><span><span>$customer = new Customer('customer@sitepoint.com', 'Joe');
</span></span><span>
</span><span><span>$data = [
</span></span><span>    <span>'customer' => [
</span></span><span>        <span>'email' => $customer->getEmail(),
</span></span><span>        <span>'name' => $customer->getName()
</span></span><span>    <span>]
</span></span><span><span>];
</span></span><span>
</span><span><span>echo json_encode($data);</span></span></span>

Now if any more change requests come in that want more data to be added to and returned from the Customer object we can just update the toJson method.

This approach has it’s own drawbacks, though. Anyone else that comes along and wants to use our Customer needs to be aware of this toJson method because it’s not something that is easily checked for, so we’d need accurate documentation. We also have to remember that this method returns JSON now, (though we could move the serialization outside the method). This makes combining Customer data with other sources of data more awkward because we have to be careful not to encode the result of this method again as that would cause some nasty bugs.

The Good

Finally, enter the JsonSerializable interface. This gives us all the flexibility of the Ugly scenario with the maintainability benefits of the Bad scenario. Though to use this interface you will need to be running PHP 5.4.0 which you really should be doing anyway, as there are many improvements over older versions.

So, to business.

<span><span><?php </span></span><span>
</span><span><span>class Customer
</span></span><span><span>{
</span></span><span>
</span><span>    <span>public $email = null;
</span></span><span>    <span>public $name = null;
</span></span><span>
</span><span>    <span>public function __construct($email, $name)
</span></span><span>    <span>{
</span></span><span>        <span>$this->email = $email;
</span></span><span>        <span>$this->name = $name;
</span></span><span>    <span>}
</span></span><span>
</span><span>    <span>public function getName()
</span></span><span>    <span>{
</span></span><span>        <span>return $this->name;
</span></span><span>    <span>}
</span></span><span>
</span><span>    <span>public function getEmail()
</span></span><span>    <span>{
</span></span><span>        <span>return $this->email;
</span></span><span>    <span>}
</span></span><span>
</span><span>    <span>public function toJson()
</span></span><span>    <span>{
</span></span><span>        <span>return json_encode([
</span></span><span>            <span>'customer' => [
</span></span><span>                <span>'email' => $this->getEmail(),
</span></span><span>                <span>'name' => $this->getName()
</span></span><span>            <span>]
</span></span><span>        <span>]);
</span></span><span>    <span>}
</span></span><span><span>}
</span></span><span>
</span><span><span>$customer = new Customer('customer@sitepoint.com', 'Joe');
</span></span><span>
</span><span><span>echo $customer->toJson();</span></span></span>

As you can see, we implement JsonSerializable by adding the interface to our class and then adding a jsonSerialize method to the body of our class to satisfy the interfaces contract.

In the jsonSerialize method we construct and return an array of the object data, just as we did with the other examples. Once again if anything changes then we can just update this one method. You’ll notice that the jsonSerialize method just returns an array.

The magic comes when you want to trigger this method, all we have to do now is json encode an instance of this class and this method will be called automatically, the array of data returned and then encoded! Now that the class implements an interface we benefit from being able to check if this class is an instanceof JsonSerializable. If you wanted you could also type hint in methods to make sure a JsonSerializable interface is passed.

Summary

With this simple implementation, we’ve removed duplication, decreased the amount of maintenance and reduced the chances of introducing bugs. We’ve also made it trivial for another person using our code to test for the ability of the object to be encoded by checking if it’s an instance of JsonSerializable.

The examples above are of course contrived, however, I hope I’ve managed to demonstrate the benefits of using this interface and inspire you to go ahead and use it yourself.

Frequently Asked Questions (FAQs) about JSONSerializable Interface

What is the main purpose of the JSONSerializable interface in PHP?

The JSONSerializable interface in PHP is primarily used to customize the JSON representation of an object. When an object is passed to the json_encode() function, if it implements the JSONSerializable interface, the jsonSerialize() method will be called, allowing the object to dictate how it should be serialized. This provides a high level of control over the JSON output, making it easier to manage complex data structures or perform transformations on the data before it is encoded.

How does the jsonSerialize() method work?

The jsonSerialize() method is a part of the JSONSerializable interface. When an object implementing this interface is passed to json_encode(), the jsonSerialize() method is automatically called. This method should return a data structure that is ready to be serialized into JSON. This could be an array, a string, a number, or even another object. The returned data will then be encoded by json_encode() into a JSON string.

Can I use JSONSerializable interface with private properties?

Yes, you can use the JSONSerializable interface with private properties. The jsonSerialize() method has access to the object’s private and protected properties, allowing you to include these in the data that is returned for serialization. This can be useful when you want to encode an object’s internal state into JSON, but still keep the properties private or protected within the class.

How can I handle exceptions in jsonSerialize() method?

If an exception is thrown within the jsonSerialize() method, it will not be caught by json_encode(). Instead, json_encode() will return false, and the exception will need to be caught and handled separately. To handle exceptions within jsonSerialize(), you can use a try-catch block within the method itself, allowing you to manage the exception and return a valid data structure for serialization.

Can I use JSONSerializable interface to decode JSON?

No, the JSONSerializable interface is only used for encoding objects into JSON. To decode JSON, you would use the json_decode() function. However, you can create a method within your class to handle the decoding and reconstruction of an object from a JSON string.

How can I use JSONSerializable interface with nested objects?

If you have an object that contains other objects and you want to encode the entire structure into JSON, each nested object must also implement the JSONSerializable interface. When json_encode() is called on the parent object, it will also call jsonSerialize() on each nested object, allowing each one to dictate how it should be serialized.

Can I use JSONSerializable interface with arrays?

Yes, you can use the JSONSerializable interface with arrays. If the array contains objects, each object should implement the JSONSerializable interface. When json_encode() is called on the array, it will call jsonSerialize() on each object within the array, allowing each one to dictate how it should be serialized.

How can I customize the JSON output with JSONSerializable interface?

You can customize the JSON output by returning a custom data structure from the jsonSerialize() method. This could be an array with custom keys, a string, a number, or another object. The data structure that you return from jsonSerialize() will be the data that is encoded into JSON.

Can I use JSONSerializable interface with multidimensional arrays?

Yes, you can use the JSONSerializable interface with multidimensional arrays. If the arrays contain objects, each object should implement the JSONSerializable interface. When json_encode() is called on the multidimensional array, it will call jsonSerialize() on each object within the array, allowing each one to dictate how it should be serialized.

Can I use JSONSerializable interface with non-associative arrays?

Yes, you can use the JSONSerializable interface with non-associative arrays. If the array contains objects, each object should implement the JSONSerializable interface. When json_encode() is called on the non-associative array, it will call jsonSerialize() on each object within the array, allowing each one to dictate how it should be serialized.

The above is the detailed content of How to Use the JsonSerializable Interface. For more information, please follow other related articles on the PHP Chinese website!