Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Serializer documentation can be improved (possibly contains an error?)

Open
#2,280 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
php, symfony
Domain
documentation

Research direction

Start with the Symfony Serializer documentation page, especially the section on changing the serialization context per item and its decorator example. Verify the getSupportedTypes caching behavior and compare it with the proposed scalable alternative; done means both examples are technically correct and the documentation clearly explains when to use each approach.

Written by the indexing model from the issue text.

Description

2 part question, both relating to (Symfony) Serializer docs.

1:
The Serializer docs show an example of decorating the json-ld normalizer to add a few fields, but wouldn't a completely custom serializer be better so the getSupportedTypes can be used to efficiently decide if this serializer should be used instead of having 20,30, maybe 100s of services decorating the json-ld normalizer and it having to go through all those layers with like if (!$data instanceof ...) or if (!is_a($type, SomeClass::class, true))

Should we add an example for a cache-able/scalable solution that doesn't involve decorating the json-ld one?

2:
Then looking at the example code here:
https://api-platform.com/docs/core/serialization/#changing-the-serialization-context-on-a-per-item-basis-for-symfony

Specifically:

    public function supportsNormalization($data, $format = null, array $context = [])
    {
        // Make sure we're not called twice
        if (isset($context[self::ALREADY_CALLED])) {
            return false;
        }

        return $data instanceof Book;
    }

    public function getSupportedTypes(?string $format): array
    {
        return [
            Book::class => true
        ];
    }

Returning true on getSupportedTypes means the usage of the serializer gets cached, and the supportsNormalization method is only checked once, then never again. So adding the self::ALREADY_CALLED in the normalize method doesn't do anything,... next time it goes through this normalizer, the supportsNormalization is skipped and boom, it now executed normalize on an item that has possibly already gone through it?

I can contribute a change for both things, but would like to get a second opinion first to see if I'm maybe missing something.

Dominant language
No language data
Stars
181
Forks
1.1k
Avg merge
1d 10h
Merged PRs (30d)
24

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from api-platform/docs

All issues in api-platform/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.