Design Document for changing SerializerInterface

Table of Contents

• Current Contract for Serialization in Magento2
• Problem Description

Current Contract for Serialization in Magento2

Since Magento 2.2 to make Magento code more secure and prevent PHP Object Injection, (OWASP) vulnerability it was decided to introduce additional abstraction layer into Magento Serialization mechanism, which would give an ability to substitute default implementation of PHP Serialization (unsafe because exploitable) in favour of JSON serialization. You can read more about these changes on Magento DevDocs.

The abstraction layer is represented by SerializerInterface with to implementations represented by Serialize (PHP Serialization) and Json (serialization based on json_encode/json_decode. Default implementation):

namespace Magento\Framework\Serialize;

/**
 * Interface for serializing
 *
 * @api
 * @since 100.2.0
 */
interface SerializerInterface
{
    /**
     * Serialize data into string
     *
     * @param string|int|float|bool|array|null $data
     * @return string|bool
     * @throws \InvalidArgumentException
     * @since 100.2.0
     */
    public function serialize($data);

    /**
     * Unserialize the given string
     *
     * @param string $string
     * @return string|int|float|bool|array|null
     * @throws \InvalidArgumentException
     * @since 100.2.0
     */
    public function unserialize($string);
}

Problem Description

Since we introduced JSON serialization, represented by \Magento\Framework\Serialize\Serializer\Json class, the class became an independent contract by its own for all the business logic which needs to make json_encode/json_decode, but not a "real" serialization of objects. For example, a business logic which handles AJAX requests coming from UI dependent directly on \Magento\Framework\Serialize\Serializer\Json, but not on SerializerInterface. And that's correct from business standpoint, there is no sense to use general interface if there is no business requirement to handle anything but JSON, for example, if Magento establish an integration with 3rd party system which protocol supports only JSON, it makes sense to use contract of \Magento\Framework\Serialize\Serializer\Json, but not SerializerInterface in this case.

Because of this JSON implementation has been marked in the codebase with @api annotation, which states that JSON class represents own contract.

/**
 * Serialize data to JSON, unserialize JSON encoded data
 *
 * @api
 * @since 100.2.0
 */
class Json implements SerializerInterface

But being used more and more not for Serialization purposes but as a layer of abstraction on top of low-level functions json_encode/json_decode it appears that the contract of JSON Serialization is too narrow to cover all the business cases where json_encode/json_decode could be applied.

Contract of json_encode:

string json_encode ( mixed $value [, int $options = 0 [, int $depth = 512 ]] )

Contract of json_decode:

mixed json_decode ( string $json [, bool $assoc = FALSE [, int $depth = 512 [, int $options = 0 ]]] )

So that community started to find a way how the option parameter could be passed to Json Serialization. The high level problem statement is that there are two contracts in fact:

1. Serialization Contract
2. JSON encoding/decoding contract which is broader than just pure serlization

But currently in Magento codebase these two contracts are identical.