Serialization groups

Roadiz CMS uses symfony/serializer to perform JSON serialization over any objects, especially Doctrine entities.

Group	Description
id	Serialize every entity id.
attribute	Serialize entities in a Attribute context.
attribute_documents	Serialize documents linked to a Attribute for each virtual field.
attribute_group	Serialize Attribute group name and translations.
attribute_node	Serialize AttributeValue in a node context (node-specific attribute values).
breadcrumbs	Serialize breadcrumb trail items within a web_response context.
children	Serializes a node along with its children using a treeWalker.
color	Serialize every entity color fields.
custom_form	Serialize entities in a CustomForm context.
custom_form_answer	Serialize CustomFormAnswer entity with its submission fields.
document	Serialize entities in a Document context.
document_copyright	Serialize Document copyright validity date range (copyrightValidSince, copyrightValidUntil).
document_display	Serialize Document information required for displaying them.
document_display_sources	Serialize Document information required for displaying alternative sources (audio, video).
document_source	Serialize minimal Document information for an alternative source (mimeType, type, relativePath).
document_filesize	Serialize Document filesize in bytes.
document_folders	Serialize Document information required for displaying attached visible folders.
document_folders_all	Serialize all Document attached folders, even not visible ones.
document_mount	Serialize Document storage mount path prefix.
document_original	Serialize Document original reference (for thumbnail documents pointing back to their original).
document_raw_relative_path	Serialize rawRelativePath when document has a RAW version and make it downloadable.
document_thumbnails	Serialize Document first available thumbnail.
folder	Serialize entities in a Folder context.
folder_children	Serialize Folder children.
folder_color	Serialize Folder color field.
folder_parent	Serialize Folder parent.
log	Serialize Log entity core fields.
log_sources	Serialize node/source context on Log entries.
log_user	Serialize user context on Log entries.
node	Serialize entities in a Node context.
node_attributes	Serialize Nodes with their attribute values.
node_children	Serialize Nodes with their children.
node_listing	Serialize Nodes and NodesSources with their listing children options. Adds listingSortOptions field to node-sources, with for example { "node.position": "ASC" } to be able to fetch children nodes in the same order as in the back office. If the current serialized node-source parent is hiding its children, listingSortOptions will contain the parent's listingSortOptions instead.
node_type	Serialize entities in a NodeType context.
nodes_sources	Serialize entities in a NodesSources context (all fields).
nodes_sources_base	Serialize entities in a NodesSources context, but with essential information.
nodes_sources_default	Serialize NodesSources fields not contained in any group.
nodes_sources_documents	Serialize documents linked to a NodesSources for each virtual field.
nodes_sources_published	Serialize NodesSources isPublished field when you fetch all NodesSources, even the unpublished ones.
nodes_sources_xxxx	Custom serialization groups are created according to your node-type fields groups. For example, if you set a field to a link group, nodes_sources_link serialization group will be automatically generated for this field. Be careful, Roadiz will use groups canonical names to generate serialization groups, it can mix _ and -.
position	Serialize every entity position fields.
realm	Serialize Realm access-control entity fields.
setting	Serialize entities in a Setting context.
setting_group	Serialize entities in a SettingGroup context.
tag	Serialize Tag.
tag_base	Serialize Tags with minimum information.
tag_children	Serialize Tags with their children, do not use with tag_parent group.
tag_color	Serialize Tags with their color field.
tag_documents	Serialize Tags with their documents.
tag_parent	Serialize Tags with their parent.
timestamps	Serialize every date-timed entity createdAt and updatedAt fields.
translated_tag	Serialize Tag with its translations collection.
translation	Serialize entities in a Translation context.
translation_base	Serialize Translation information required for displaying them.
url_alias	Serialize UrlAlias entity fields.
urls	Serialize the url fields of every entity.
user	Serialize entities in a User context.
user_chroot	Serialize User chroot node restriction.
user_group	Serialize User entity with its groups.
user_identifier	Serialize User entity with its identifier (may be a personal information).
user_personal	Serialize User entity with its personal information.
user_public	Serialize public-facing User fields from AbstractHuman.
user_role	Serialize User entity with its roles.
user_security	Serialize User security and authentication fields.
walker	Serializes a treeWalker children.
walker_metadata	Serializes a treeWalker metadata.
web_response	Serialize the top-level WebResponse API envelope fields.

Enriching normalized items

To add or change fields in the API Platform output of an entity, implement RZ\Roadiz\CoreBundle\Serializer\Enricher\NormalizationEnricherInterface. Enrichers are autoconfigured, and a single EnrichingItemNormalizer (decorating api_platform.jsonld.normalizer.item and api_platform.serializer.normalizer.item) runs them after API Platform has normalized the object.

namespace App\Serializer\Enricher;

use App\GeneratedEntity\NSMenuLink;
use RZ\Roadiz\CoreBundle\Serializer\Enricher\NormalizationEnricherInterface;
use Symfony\Cmf\Component\Routing\RouteObjectInterface;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

final readonly class MenuLinkPathEnricher implements NormalizationEnricherInterface
{
    public function __construct(private UrlGeneratorInterface $urlGenerator)
    {
    }

    public function supports(object $data, ?string $format, array $context): bool
    {
        return $data instanceof NSMenuLink;
    }

    /**
     * @param NSMenuLink $data
     */
    public function enrich(array $normalized, object $data, ?string $format, array $context): array
    {
        $target = $data->getLinkInternalReferenceSources()[0] ?? null;
        $normalized['url'] = null !== $target
            ? $this->urlGenerator->generate(RouteObjectInterface::OBJECT_BASED_ROUTE_NAME, [
                RouteObjectInterface::ROUTE_OBJECT => $target,
            ])
            : $data->getLinkExternalUrl();

        return $normalized;
    }
}

• supports() is called for every normalized object: keep it cheap, instanceof first.
• enrich() only runs when API Platform returned an array (not an IRI string).
• Each enricher run is measured in the Symfony profiler under the serializer Stopwatch category, there is no need to add your own.

Ordering

Enrichers run in descending tag priority, set with #[AsTaggedItem(priority: …)] (default 0). Core enrichers use the following priorities, so pick yours accordingly:

Priority	Enricher
21	FolderEnricher
20	DocumentEnricher
19	DocumentSourcesEnricher
18	TagTranslationEnricher
15	AttributeValueEnricher, CustomFormEnricher
5	NodesSourcesPathEnricher (adds url unless already set)
-10	NodesSourcesTypeEnricher (JSON-LD @type only)

Normalizing nested objects

When an enricher adds related objects (documents, folders…), normalize them through the Serializer: implement Symfony\Component\Serializer\Normalizer\NormalizerAwareInterface (with NormalizerAwareTrait) and call $this->normalizer->normalize($related, $format, $context). The EnrichingItemNormalizer injects the Serializer for you. Never call an inner normalizer directly: other enrichers and project decorators would not apply to the nested objects. Restrict $context['groups'] for nested objects to avoid normalization loops.

Migrating from AbstractPathNormalizer

AbstractPathNormalizer decorators still work, but are deprecated: each one adds a layer to every supportsNormalization() call the Serializer makes, for every normalized object. To migrate one:

1. Implement NormalizationEnricherInterface instead of extending AbstractPathNormalizer.
2. Move the instanceof and context checks into supports().
3. Move the code that runs after $this->decorated->normalize() into enrich(), and return the array.
4. Replace $this->decorated->normalize($nested, …) with $this->normalizer->normalize($nested, …) (see above).
5. Remove both decorates: service definitions from config/services.yaml. Convert their decoration_priority into an #[AsTaggedItem] priority if order matters.