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.

<?php

class Customer
{

    private $email = null;
    private $name = null;

    public function __construct($email, $name)
    {
        $this->email = $email;
        $this->name = $name;
    }

    public function getName()
    {
        return $this->name;
    }

    public function getEmail()
    {
        return $this->email;
    }
}

$customer = new Customer('customer@sitepoint.com', 'Joe');

$data = [
    'customer' => [
        'email' => $customer->getEmail(),
        'name' => $customer->getName()
    ]
];

echo json_encode($data);

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.

<?php

class Customer
{

    public $email = null;
    public $name = null;

    public function __construct($email, $name)
    {
        $this->email = $email;
        $this->name = $name;
    }

    public function getName()
    {
        return $this->name;
    }

    public function getEmail()
    {
        return $this->email;
    }

    public function toJson()
    {
        return json_encode([
            'customer' => [
                'email' => $this->getEmail(),
                'name' => $this->getName()
            ]
        ]);
    }
}

$customer = new Customer('customer@sitepoint.com', 'Joe');

echo $customer->toJson();

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.

<?php

class Customer implements JsonSerializable
{

    private $name;
    private $email;

    public function __construct($name, $email)
    {
        $this->name = $name;
        $this->email = $email;
    }

    public function getName()
    {
        return $this->name;
    }

    public function getEmail()
    {
        return $this->email;
    }

    public function jsonSerialize()
    {
        return [
            'customer' => [
                'name' => $this->name,
                'email' => $this->email
            ]
        ];
    }
}

$customer = new Customer('customer@sitepoint.com', 'Joe');

echo json_encode($customer);

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