[RFC] Using decoration over inheritance for Normalizers

[joelwurtz]

Actually all Item Normalizers (HAL / JSON-LD / Json Api) extends the AbstractItemNormalizer to add their context and informations.

I'm actually working on a library that change the way of serializing / deserializing object by using generated code (https://github.com/janephp/automapper) insted of the PropertyAccess Component. This change allows significant performance boost

see https://blackfire.io/profiles/compare/c6fa2145-c3aa-46f9-a211-538c6dc576a5/graph or https://travis-ci.org/php-serializers/ivory-serializer-benchmark/builds/460744766?utm_source=github_status&utm_medium=notification

The example try to serilalize 10000 objects, that's an use case that we have where we need to return a lots of data and where we cannot use cache

However for correct integration with API Platform i need to rewrite all the existing normalizers since class are final and use inheritance.

I belive by using decoration (injecting a normalizer that does the item normalization / denormalization instead of calling the parent class) this would be far easier to handle this use case. I'm willing to work on the PR if that's something you want to support.

[dunglas]

It's something we definitely want, and that is currently being improved directly in Symfony. @fbourigault has already provided some patches in this way (some are included in SF 4.2), but they are still some work to do. As usual, all help on this will be very welcome.

[joelwurtz]

For decoration ? Or code generation ?

[dunglas]

Decoration.

[dunglas]

Composition actually.

[joelwurtz]

I began to do some works here, but i'm a bit loss with all the things that Normalizers do on API Platform, some of the ObjectNormalizer features of Symfony are overrided here, and it's hard to know why.

Is there some kinds of docs that explain the whole Normalizer architecture of API Platform ? Or Features that it needs in order to work correctly ?

[soyuka]

It's really internal so no docs here, only code but I'm available to help you. Note for the sake of simplicity I'm skipping Elasticsearch and Graphql.

There are two kind of normalizers in ApiPlatform:

• CollectionNormalizer
• ItemNormalizer

You'll be more interested by the later as it is an extension of the ObjectNormalizer.
Each normalizer is declined in every supported formats:

• For collections: JsonApi\Serializer\CollectionNormalizer, Hydra\Serializer\CollectionNormalizer, Hal\Serializer\CollectionNormalizer
• For items: Serializer\ItemNormalizer, JsonApi\Serializer\ItemNormalizer, JsonLd\Serializer\ItemNormalizer, Hal\Serializer\ItemNormalizer

Let's skip collections for now (most of them extend our AbstractCollectionNormalizer that is a NormalizerInterface).

For items, they're all extending the ApiPlatform\Core\Serializer\AbstractItemNormalizer that extends the Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer.

The ApiPlatform\Core\Serializer\ItemNormalizer is only there for the denormalization when it's an operation where we need to update an item. It's responsible to fetch this item according to the given IRI (eg PUT /dummies/1 will fetch Dummy with id 1). This object will be stored in the $context[self::OBJECT_TO_POPULATE] (which is defined by symfony's AbstractObjectNormalizer). It then calls parent::denormalize.

Every other ItemNormalizer extends our AbstractItemNormalizer and always calls parent::normalize or parent::denormalize accordingly.
The AbstractItemNormalizer is there to override some of the methods mainly to update relations when it finds IRIs instead of just working on objects. The rest are some other cache or context-related specific things.

I hope this helps, don't hesitate to reach me on slack (ping in a private conv' so I get notified).

[joelwurtz]

Thanks for this explanation, it offer great insight on how this works.

I'm still wondering how to use composition here, as there is 2 options:

• Having an AbstractItemNormalizer that use composition and directly implements Normalizer and Denormalizer interfaces
• Having each ItemNormalizer (JSON / JSON-LD / HAL) use composition and directly implements Normalizer and Denormalizer interface, and create a RessourceItemNormalizer (which is the current AbstractItemNormalizer) as an internal final class.

I would prefer option 1, (less code IMO), and injecting in it the ObjectNormalizer of symfony, but i'm afraid it may collapse on some features (as both will try to do the same things, and potentially differently). Do we need in this case our own ObjectNormalizer ?

On option 2, each ItemNormalizer would have more work to do (but maybe we can have another AbstractItemNormalizer ?).

Goal of this would be to change the internal ObjectNormalizer so someone can write its custom Normalizer for an object and use composition to add API Platform Features around it.

[soyuka]

There isn't much we can do it feels, we're now waiting for symfony/symfony#51718