Skip to content
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.

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

Update serialization.md #1490

Open
wants to merge 9 commits into
base: 3.4
Choose a base branch
from
Open
Changes from 8 commits
Commits
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
Original file line number Diff line number Diff line change
@@ -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.

@@ -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