Serialization Groups

Serialization groups allow you to define which properties of an entity should be serialized when a specific group is requested. This is useful when you want to expose different properties of an entity depending on the context.

Usage

To use serialization groups, you need to define a group in the Groups annotation. The annotation is used to control which properties are serialized in the response. The following example shows how to use serialization groups:

<?php

namespace App\Entity;

// ...

class Environment
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: "integer")]
    #[Groups(['collection', 'export'])]
    private ?int $id = null;

    #[ORM\Column(type: "string", length: 255)]
    #[Groups(['collection', 'detail', 'export'])]
    private ?string $name = null;

    #[ORM\Column(type: "string", length: 255, nullable: true)]
    #[Groups(['collection', 'detail', 'export'])]
    private ?string $description = null;

// ...
}

In this example, the Environment entity has three properties: id, name, and description. The id property is annotated with the Groups attribute and the groups collection and export. This means that the id property will be serialized when the collection or export group is requested.

The name and description properties are also annotated with the Groups attribute, but with different groups. This means that the name and description properties will be serialized when the collection, detail, or export group is requested.

API Platform uses Symfony's serializer component to serialize entities. You can use the serializer component directly to serialize entities with serialization groups.

An example of how to use serialization groups is shown below:

<?php

namespace App\API\Serializer;

use Symfony\Component\Serializer\Encoder\JsonEncoder;
use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
use Symfony\Component\Serializer\Mapping\Loader\AttributeLoader;
use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\Serializer\Serializer;


class EntitySerializer
{
    /**
     * @var string
     *
     * The group used for exporting entities.
     */
    public const EXPORT_GROUP = 'export';

    public function serializeEntities(mixed $entities): string
    {
        $classMetadataFactory = new ClassMetadataFactory(new AttributeLoader());
        $serializer = new Serializer(
            [new ObjectNormalizer($classMetadataFactory)],
            [new JsonEncoder()]
        );

        return $serializer->serialize($entities, JsonEncoder::FORMAT, ['groups' => self::EXPORT_GROUP]);
    }

    public function deserializeEntity(string $data, string $entityClass): mixed
    {
        $serializer = new Serializer(
            [new GetSetMethodNormalizer(), new ArrayDenormalizer()],
            [new JsonEncoder()]
        );

        return $serializer->deserialize($data, $entityClass, JsonEncoder::FORMAT);
    }
}

In this example, the EntitySerializer class is used to serialize and deserialize entities. The serializeEntities method is used to serialize entities with the export group. The deserializeEntity method is used to deserialize entities.