Skip to content

Update serialization.md #1490

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 9 commits into
base: 3.4
Choose a base branch
from
Open

Update serialization.md #1490

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4dd7746
Update serialization.md
jzabrodin Dec 13, 2021
6c92507
Merge branch 'api-platform:2.6' into patch-2
jzabrodin Dec 28, 2021
17c170e
Update core/serialization.md
jzabrodin Dec 28, 2021
5babbc7
Update core/serialization.md
jzabrodin Dec 28, 2021
ee974c1
Update serialization.md
jzabrodin Dec 28, 2021
3cf7f0d
Apply suggestions from code review
vincentchalamon Jul 20, 2022
d79c065
Merge branch '2.6' into patch-2
Aug 15, 2022
5ee78a1
Fix review issues
Aug 15, 2022
cfce698
Update core/serialization.md
jzabrodin Sep 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 101 additions & 1 deletion core/serialization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ The main serialization process has two stages:
![Serializer workflow](images/SerializerWorkflow.png)

> As you can see in the picture above, an array is used as a man-in-the-middle. This way, Encoders will only deal with turning specific formats into arrays and vice versa. The same way, Normalizers will deal with turning specific objects into arrays and vice versa.
-- [The Symfony documentation](https://symfony.com/doc/current/components/serializer.html)
> -- [The Symfony documentation](https://symfony.com/doc/current/components/serializer.html)

Unlike Symfony itself, API Platform leverages custom normalizers, its router and the [data provider](data-providers.md) system to perform an advanced transformation. Metadata are added to the generated document including links, type information, pagination data or available filters.

Expand Down Expand Up @@ -41,6 +41,106 @@ feature of the Symfony Serializer component.
In addition to groups, you can use any option supported by the Symfony Serializer. For example, you can use [`enable_max_depth`](https://symfony.com/doc/current/components/serializer.html#handling-serialization-depth)
to limit the serialization depth.

[codeSelector]

```php
<?php
// api/src/Entity/Book.php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Serializer\Annotation\MaxDepth;
Comment on lines +52 to +54
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would recommend to target 4.0 branch instead of 3.4, and update the imports as following:

Suggested change
use ApiPlatform\Core\Annotation\ApiResource;
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Serializer\Annotation\MaxDepth;
use ApiPlatform\Metadata\ApiResource;
use Symfony\Component\Serializer\Attribute\Groups;
use Symfony\Component\Serializer\Attribute\MaxDepth;


#[ApiResource(
normalizationContext: ['groups' => 'read', 'enable_max_depth' => true],
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
normalizationContext: ['groups' => 'read', 'enable_max_depth' => true],
normalizationContext: ['groups' => ['read'], 'enable_max_depth' => true],

denormalizationContext: ['groups' => ['write']],
)]
class Book
{
#[Groups(["read", "write"])]
public $name;

#[Groups("write"), MaxDepth(1)]
public $author;

// ...
}
```

```yaml
# api/config/api_platform/resources.yaml
resources:
App\Entity\Book:
attributes:
normalization_context:
groups: ['read']
enable_max_depth: true
denormalization_context:
groups: ['write']

# api/config/serialization/Book.yaml
App\Entity\Book:
properties:
author:
groups: ['write']
max_depth: 1
```

```xml
<!-- api/config/api_platform/resources.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<resources xmlns="https://api-platform.com/schema/metadata/resources-3.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
https://api-platform.com/schema/metadata/resources-3.0.xsd">
<resource class="App\Entity\Book">
<normalizationContext>
<values>
<value name="groups">
<values>
<value>read</value>
</values>
</value>
<value name="enable_max_depth">
<values>
<value>true</value>
</values>
</value>
</values>
</normalizationContext>
<denormalizationContext>
<values>
<value name="groups">
<values>
<value>write</value>
</values>
</value>
</values>
</denormalizationContext>
</resource>
</resources>


<!-- api/config/serialization/Book.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
http://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd">
<class name="App\Entity\Book">
<attribute name="author">
<group>write</group>
<max_depth>1</max_depth>
</attribute>
</class>
</serializer>
```

[/codeSelector]


### Configuration

Just like other Symfony and API Platform components, the Serializer component can be configured using annotations, XML
Expand Down