Merge pull request #84 from swagindustries/doc-circular-reference

📝 Add troubleshooting section

README.md

@@ -41,16 +41,11 @@ please refer to the
 
 You may want to read the [getting started doc](./docs/getting-started.md) at this point!
 
+If you're experimenting an issue while trying Melodiia, you will maybe find the solution in the [troubleshooting](./docs/troubleshooting.md) section.
+
 One last thing
 --------------
 
 I ([Nek-](https://github.com/Nek-)) designed Melodiia while I was working at Biig in the mean time. This [presentation of Melodiia @Biig-io](https://docs.google.com/presentation/d/1dtxUOzZFGRq7Ar5YV5aZ6AN60RhDbf_0OcXKj5iiDS8/edit?usp=sharing) is related to an old version of Melodiia but can still helps you to understand what is melodiia and how it's different from API Platform (TL;DR: Melodiia does less).
 
 Feel free to open an issue, if you encounter problems while implementing Melodiia.
-
-FAQ
----
-
-### Blank page on documentation
-
-You probably forget to install assets. `bin/console assets:install`.

couscous.yml

@@ -35,3 +35,6 @@ menu:
         forms:
             text: Forms Reference
             relativeUrl: docs/form-types.html
+        troubleshooting:
+            text: Troubleshooting
+            relativeUrl: docs/troubleshooting.html

docs/troubleshooting.md

@@ -0,0 +1,34 @@
+# Troubleshooting
+
+_Here is a list of classic error you may experiment with Melodiia and how to fix it_
+
+
+### Blank page on documentation
+
+You probably forget to install assets. `bin/console assets:install`.
+
+## Uncaught PHP Exception Symfony\Component\Serializer\Exception\CircularReferenceException
+
+This error is disturbing but not related to Melodiia. It happens because you return an object that have a reference to
+itself in one of its children (or sub-children).
+
+Let's consider the following couple of entities:
+
+```php
+class Product
+{
+    public ArrayCollection $variants;
+}
+
+class Variant
+{
+    public Product $product;
+}
+```
+
+When Melodiia tries to serialize your product, it will also serialize the variants associated to the product, then the product itself.
+
+The serializer is well-designed and detect this issue, this is why you're getting this exception instead of an infinite loop!
+
+To fix it, you need to use serialization groups, it's
+[documented on Symfony documentation](https://symfony.com/doc/current/serializer.html#using-serialization-groups-attributes).