As part of the API first initiative I have been working a lot with the serialization module. This module is a key member of the web-service-oriented modules present both in core and contrib.
The main focus of the serialization module is to encapsulate Symfony's serialization component. Note that there is no separate deserialization component. This single component is in charge of serializing and deserializing incoming data.
When I started working with this component the first question that I had was "What does serialize mean? And how is it different from deserializing?". In this article I will try to address this question and give a brief introduction on how to use it in Drupal 8. In the second part of the article I will show you how to use it in Drupal step-by-step.
Serializers encoders and normalizers
Serialization is the process of normalizing and then encoding an input object. Similarly, we refer to deserialization as the process of decoding and then denormalizing an input string. Encoding and decoding are the reverse processes of one another, just like normalizing and denormalizing are.
In simple terms, we want to be able to turn an object of class MyClass into a particular string representation, and then be able to turn that string back into the original object.
An encoder is in charge of converting simple data—a set of scalars, arrays and stdClass objects—into a string. The resulting string is a convenient way to store or transport the original object. A decoder performs the opposite function; it will take that encoded string and transform it into an array that’s ready to use. json_encode and json_decode are good examples of a commonly used (de)encoder. XML is another example of a format to encode to. Note that for an object to be correctly encoded it needs to be normalized first. Consider the following example where we encode and decode an object without any normalization or denormalization.
class MyClass {}
$obj = new MyClass();
var_dump($obj); // Outputs: object(MyClass) (0) {}
var_dump(json_decode(json_encode($obj))); // Outputs: object(stdClass) (0) {}
You can see in the code above that the composition of the two inverse operations is not the same original object of type MyClass. This is because the encoding operation loses information if the input data is not a simple set of scalars, arrays, and stdClass objects. Once that information is lost, the decoder cannot get it back.
Serialization diagram from the serializer component documentation page.
One of the reasons why we need normalizers and denormalizers is to make sure that data is correctly simplified before being turned into a string. It also needs to be upcast to a typed object after being parsed from a string. Another reason is that different (de)normalizers allow us to work with different formats of the data. In the REST subsystem we have different normalizers to transform a Node object into the JSON, HAL or JSON API formats. Those are JSON objects with different shapes, but they contain the same information. We also have different denormalizers that will take a simplified JSON, HAL or JSON API payload and turn it into a Node object.
(De)Normalization in Drupal
The normalization of content entities is a very convenient way to express the content in a particular format and shape. So formatted, the data can be exported to other systems, stored as a text-based document, or served via an HTTP request. The denormalization of content entities is a great way to import content into your Drupal site. Normalization and denormalization can also be combined to transform a document from one format to another. Imagine that we want to transform a HAL document into a JSON API document. To do so, you need to denormalize the HAL input into a Node object, and then normalize it into the desired JSON API document.
A good example of the normalization process is the Data Model module. In this case instead of normalizing content entities such as nodes, the module normalizes the Typed Data definitions. The typed data definitions are the internal Drupal objects that define the schemas of the data for things like fields and properties. An integer field will contain a property (the value property) of type IntegerData. The Data Model module will take object definitions and simplify (normalize) them. Then they can be converted to a string following the JSON Schema format to be used in external tools such as beautiful documentation generators. Note how a different serialization could turn this typed data into a Markdown document instead of JSON Schema string.
Adding a new (de)normalizer to the system
In order to add a new normalizer to the system you need to create a new tagged service in custom_module.services.yml.
serializer.custom_module.my_class_normalizer:
class: Drupal\custom_module\Normalizer\MyClassNormalizer
tags:
- { name: normalizer, priority: 25 }The class for this service should implement the normalization interface in the Symfony component Symfony\Component\Serializer\Normalizer\NormalizerInterface. This normalizer service will be in charge of declaring which types of objects it knows how to normalize and denormalize—that would be MyClass in our previous example. This way the serialization module uses it when an object of type MyClass needs to be (de)normalized. Since multiple modules may provide a service that supports normalizing MyClass objects, the serialization module will use the priority key in the service definition to resolve the normalizer to be used.
As you would expect, in Drupal you can alter and replace existing normalizers and denormalizers so they provide the output you need. This is very useful when you are trying to alter the output of the JSON API, JSON or HAL web services.
In a next article I will delve deeper into how to create a normalizer and a denormalizer from scratch, by creating an example module that (de)normalizes nodes.
Conclusion
The serialization component in Symfony allows you to deal with the shape of the data. It is of the utmost importance when you have to use Drupal data in an external system that requires the data to be expressed in a certain way. With this component, you can also perform the reverse process and create objects in Drupal that come from a text representation.
In a following article I will show you an introduction on how to actually work with (de)normalizers in Drupal.