[Serializer] Allow to provide (de)normalization context in mapping

[ogizanagi]

Q	A
Branch?	5.x
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	Fix #39039
License	MIT
Doc PR	TODO

As explained in the linked feature request, this brings the ability to configure context on a per-property basis, using Serializer mapping.

Considering:

use Symfony\Component\Serializer\Annotation as Serializer;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

class Foo
{
    /**
     * @Serializer\Context({ DateTimeNormalizer::FORMAT_KEY = 'Y-m-d' })
     */
    public \DateTime $date;

    public \DateTime $anotherDate;
}

$date will be formatted with a specific format, while $anotherDate will use the default configured one (or the one provided in the context while calling ->serialize() / ->normalize()).

It can also differentiate normalization and denormalization contexts:

use Symfony\Component\Serializer\Annotation as Serializer;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

class Foo
{
    /**
     * @Serializer\Context(
     *   normalizationContext = { DateTimeNormalizer::FORMAT_KEY = 'Y-m-d' },
     *   denormalizationContext = { DateTimeNormalizer::FORMAT_KEY = \DateTime::COOKIE },
     * )
     */
    public \DateTime $date;
}

As well as act differently depending on groups:

use Symfony\Component\Serializer\Annotation as Serializer;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

class Foo
{
    /**
     * @Serializer\Groups({ "extended" })
     * @Serializer\Context({ DateTimeNormalizer::FORMAT_KEY = \DateTime::RFC3339 })
     * @Serializer\Context(
     *   context = { DateTimeNormalizer::FORMAT_KEY = \DateTime::RFC3339_EXTENDED },
     *   groups = {"extended"},
     * )
     */
    public \DateTime $date;
}

The annotation can be repeated as much as you want to handle the different cases.
Context without groups is always applied first, then context for groups are merged in the provided order.
Context provided when calling ->serialize() / ->normalize() acts as the defaults for the properties without context provided in the metadata.

XML mapping (see tests) is a lot verbose due to the required structure to handle groups.

Such metadata contexts are also forwarded to name converters, max depth handlers, callbacks, ...

Of course, PHP 8 attributes are also supported:

use Symfony\Component\Serializer\Annotation as Serializer;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

class Foo
{
    #[Serializer\Groups(["extended"])]
    #[Serializer\Context([DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339])]
    #[Serializer\Context(
      context: [DateTimeNormalizer::FORMAT_KEY => \DateTime::RFC3339_EXTENDED],
      groups: ["extended"],
    )]
    public \DateTime $date;
}

The PR should be ready for first batch of reviews / discussions.

• Make Fabbot happy in 5.2
• Missing @Context unit tests
• rework xml & phpize values
• Fix lowest build issue with annotations => bumped doctrine annotations to 1.7, as for other components

[dunglas]

I haven't reviewed the code yet but I like the idea! Could we also allow to set this annotation on classes? In this case, the context will be applied to the class and all its properties.

[ogizanagi]

Using * should be fine since #33540 already relies on this. So no one should name their groups *.
Otherwise, previous version used an empty string, but we could simply opt for a distinct defaultDenormalizationContext property as well.

[ogizanagi]

I haven't reviewed the code yet but I like the idea! Could we also allow to set this annotation on classes? In this case, the context will be applied to the class and all its properties.

Indeed, I also had this case in mind. I'd say let's polish this one first and iterate over. I don't think it would bring any compatibility issue (anyway we have time until 5.3 release).

Note that applying a context on an object property should already do it right now. But we miss a way to add it on class-level, for the root object for instance.

[chalasr]

Looks good!

[dunglas]

Suggested change

	class Context
	final class Context

[ogizanagi]

Done. But we can imagine some legit use-cases for extending it. See #38993 (comment) for instance.
WDYT?

[derrabus]

This feature could come in handy in my current project.

[fabpot]

Thank you @ogizanagi.