Help handle slate model version updates (v0.40 → v0.46)

[e1himself]

Migrating content from one version to another is always a painful task. Especially when there are structural changes.

It would be great if this library did provide version-aware Value serialization.

A good example is Slate v0.46 update that merges Leaf and Text nodes data into Text node.

Before v0.46:

{
    "object": "text",
    "leaves": [
        {
            "object": "leaf",
            "text": "Hello",
            "marks": []
        }
    ]
}

After v0.46:

{
    "object": "text",
    "text": "Hello",
    "marks": []
}

[e1himself]

Fixed with #24

[e1himself]

So now the library does support serialization and deserialization for multiple Slate JSON versions, making it possible to gradually migrate database content to the new Slate version. At the moment of writing this, prezly/slate-php does support three (slightly) different JSON serialization formats (and can be extended to more in future):

• v0.27 ... v0.39 — block nodes with isVoid property
• v0.40 ... v0.45 — isVoid dropped
• v0.46 ... ? — leaf objects are not used anymore

This helps to disconnect Slate backend model upgrade from Slate frontend package.

---

Here's how we handle the v0.40 → v0.46 upgrade.

1. We've implemented a preconfigured Value serializer to be used throughout our application.

   class DefaultSerializer implements ValueSerializer
   {
       /** @var string|null */
       private $implied_version;
   
       /** @var string|null */
       private $baseline_version;
   
       /** @var \Prezly\Slate\Serialization\ValueSerializer */
       private $serializer;
   
       public function __construct(?string $implied_version = null, ?string $baseline_version = null)
       {
           $this->implied_version = $implied_version ?? '0.40';
           $this->baseline_version = $baseline_version ?? '0.40';
           $this->serializer = new Serializer($this->baseline_version, JSON_UNESCAPED_UNICODE);
       }
   
       public function toJson(Value $value, ?string $version = null): string
       {
           return $this->serializer->toJson($value, $version);
       }
   
       public function fromJson(string $value, ?string $default_version = null): Value
       {
           return $this->serializer->fromJson($value, $default_version ?? $this->implied_version);
       }
   }

2. The application always serializes/deserializes Slate values using the above DefaultSerializer. This allows us to normalize all the incoming slate content to the baseline version. Baseline version is the version of the frontend Slate JS package.

3. When the frontend is updated, we bump the baseline version to 0.46 to start generating the new Value JSON without leaf objects. All the previously db-stored content will be automatically translated to the new 0.46 format.

4. We can then iterate over all the db values to gradually re-write them to the newest baseline version, if we want to.