[JsonEncoder] Add component documentation

[mtarld]

Fixes #20461

[mtarld]

The remaining failure is due to the fact that the https://github.com/symfony-tools/symfony-application application does not have the src/Encodable folder.

Should we create it? Or should we add the issue to the baseline? Or maybe commenting that configuration?

[TheoD02]

Suggested change

	$propertyMetadataMap = $this->decorated->load($className, $config, $context);
	$propertyMetadataMap = $this->decorated->load($className, $options, $context);

[MrYamous]

Suggested change

	To improve memory efficiency, the JsonEncoder creates _`ghost objects`: https://en.wikipedia.org/wiki/Lazy_loading#Ghost
	To improve memory efficiency, the JsonEncoder creates `ghost objects`_

And at the bottom of the file :
.. _ghost objects: https://en.wikipedia.org/wiki/Lazy_loading#Ghost

[wouterj]

Hi @mtarld. Thanks a lot for starting this and providing so much valuable documentation early in the development phase!

Before reviewing the whole document, we must think about the position of the component in the documentation. We've mostly stopped using the components/ directory. Instead, we focus on the "guides" and document framework usage. This component is a bit more challenging, as it belongs to the "Serialization" topic that currently belongs to the Serializer component. We've discussed this a bit with the core team during the SymfonyCon:

I think the best way would be to move this article to serializer/json_encoder.rst, and add a little section at the start of serializer.rst mentioning this component and when you should use instead of the Serializer component (e.g. a compact version of the "Serializer or JsonEncoder?" section). But we're of course open if people have better ideas on how to position this new component in the ecosystem!

---

Something that might also be interesting is adding a php-standalone tab to some of the code examples, showing how to use this component standalone. You can see this in use in the main serializer.rst for instance.

[wouterj]

What do we think about adding this config + the src/Encodable/ direction to a recipe for symfony/json-encoder? Or is there a common use-case of JsonEncoder where you wouldn't want this?

[mtarld]

Sure, I think that this recipe will be really useful!
About the Encodable name, do you think it is clear enough, or should we find another name?

[wouterj]

I think I was slightly confused here (and only noticed it when you asked about the name). This config option configures where our DTOs live, so we can generate the code at warmup instead of runtime? That might be a bit too application-specific to include in a recipe (would be cool if we could do auto discovery based on a PHP attribute or something, but that's a mechanism we do not yet have for non-services atm).

If I'm understanding this correctly, I would also suggest moving this slightly more down in the documentation. Let's first show people the high level usage, so they understand how the component works, and then suggest they pre-generate the required PHP code.

I guess that will also fix the build error, as src/Dto/ exists further down in the article (because we create the Cat example entity).

(btw, I'm planning on reading the whole article this week, depending on how much work there is in the office 😄 )

[mtarld]

Yes you're totally right, let's move the "cache generation" section a bit later 🙂