Skip to content

Commit bec0676

Browse files
javiereguiluzjaviereguiluz
committed
minor #20777 [Serializer] Document named serializers (HypeMC)
This PR was merged into the 7.2 branch. Discussion ---------- [Serializer] Document named serializers Closes #20235 Commits ------- 1b09d4c [Serializer] Document named serializers
2 parents 3185f7e + 1b09d4c commit bec0676

File tree

1 file changed

+249
-0
lines changed

1 file changed

+249
-0
lines changed

‎serializer.rst‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1537,6 +1537,255 @@ like:
15371537
PropertyNormalizer::NORMALIZE_VISIBILITY => PropertyNormalizer::NORMALIZE_PUBLIC | PropertyNormalizer::NORMALIZE_PROTECTED,
15381538
]);
15391539

1540+
Named Serializers
1541+
-----------------
1542+
1543+
.. versionadded:: 7.2
1544+
1545+
Named serializers were introduced in Symfony 7.2.
1546+
1547+
Sometimes, you may need multiple configurations for the serializer, such
1548+
as different default contexts, name converters, or sets of normalizers and
1549+
encoders, depending on the use case. For example, when your application
1550+
communicates with multiple APIs, each with its own set of rules.
1551+
1552+
This can be achieved by configuring multiple instances of the serializer
1553+
using the ``named_serializers`` option:
1554+
1555+
.. configuration-block::
1556+
1557+
.. code-block:: yaml
1558+
1559+
# config/packages/serializer.yaml
1560+
framework:
1561+
serializer:
1562+
named_serializers:
1563+
api_client1:
1564+
name_converter: 'serializer.name_converter.camel_case_to_snake_case'
1565+
default_context:
1566+
enable_max_depth: true
1567+
api_client2:
1568+
default_context:
1569+
enable_max_depth: false
1570+
1571+
.. code-block:: xml
1572+
1573+
<!-- config/packages/serializer.xml -->
1574+
<?xml version="1.0" encoding="UTF-8" ?>
1575+
<container xmlns="http://symfony.com/schema/dic/services"
1576+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1577+
xmlns:framework="http://symfony.com/schema/dic/symfony"
1578+
xsi:schemaLocation="http://symfony.com/schema/dic/services
1579+
https://symfony.com/schema/dic/services/services-1.0.xsd
1580+
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
1581+
1582+
<framework:config>
1583+
<framework:serializer>
1584+
1585+
<framework:named-serializer
1586+
name="api_client1"
1587+
name-converter="serializer.name_converter.camel_case_to_snake_case"
1588+
>
1589+
<framework:default-context>
1590+
<framework:enable_max_depth>true</framework:enable_max_depth>
1591+
</framework:default-context>
1592+
</framework:named-serializer>
1593+
1594+
<framework:named-serializer name="api_client2">
1595+
<framework:default-context>
1596+
<framework:enable_max_depth>false</framework:enable_max_depth>
1597+
</framework:default-context>
1598+
</framework:named-serializer>
1599+
1600+
</framework:serializer>
1601+
</framework:config>
1602+
</container>
1603+
1604+
.. code-block:: php
1605+
1606+
// config/packages/serializer.php
1607+
use Symfony\Config\FrameworkConfig;
1608+
1609+
return static function (FrameworkConfig $framework): void {
1610+
$framework->serializer()
1611+
->namedSerializer('api_client1')
1612+
->nameConverter('serializer.name_converter.camel_case_to_snake_case')
1613+
->defaultContext([
1614+
'enable_max_depth' => true,
1615+
])
1616+
;
1617+
$framework->serializer()
1618+
->namedSerializer('api_client2')
1619+
->defaultContext([
1620+
'enable_max_depth' => false,
1621+
])
1622+
;
1623+
};
1624+
1625+
You can inject these different serializer instances
1626+
using :ref:`named aliases <autowiring-multiple-implementations-same-type>`::
1627+
1628+
namespace App\Controller;
1629+
1630+
// ...
1631+
use Symfony\Component\DependencyInjection\Attribute\Target;
1632+
1633+
class PersonController extends AbstractController
1634+
{
1635+
public function index(
1636+
SerializerInterface $serializer, // Default serializer
1637+
SerializerInterface $apiClient1Serializer, // api_client1 serializer
1638+
#[Target('apiClient2.serializer')] // api_client2 serializer
1639+
SerializerInterface $customName,
1640+
) {
1641+
// ...
1642+
}
1643+
}
1644+
1645+
Named serializers are configured with the default set of normalizers and encoders.
1646+
1647+
You can register additional normalizers and encoders with a specific named
1648+
serializer by adding a ``serializer`` attribute to
1649+
the :ref:`serializer.normalizer <reference-dic-tags-serializer-normalizer>`
1650+
or :ref:`serializer.encoder <reference-dic-tags-serializer-encoder>` tags:
1651+
1652+
.. configuration-block::
1653+
1654+
.. code-block:: yaml
1655+
1656+
# config/services.yaml
1657+
services:
1658+
# ...
1659+
1660+
Symfony\Component\Serializer\Normalizer\CustomNormalizer:
1661+
# Prevent this normalizer from automatically being included in the default serializer
1662+
autoconfigure: false
1663+
tags:
1664+
# Include this normalizer in a single serializer
1665+
- serializer.normalizer: { serializer: 'api_client1' }
1666+
# Include this normalizer in multiple serializers
1667+
- serializer.normalizer: { serializer: [ 'api_client1', 'api_client2' ] }
1668+
# Include this normalizer in all serializers (including the default one)
1669+
- serializer.normalizer: { serializer: '*' }
1670+
1671+
.. code-block:: xml
1672+
1673+
<!-- config/services.xml -->
1674+
<?xml version="1.0" encoding="UTF-8" ?>
1675+
<container xmlns="http://symfony.com/schema/dic/services"
1676+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1677+
xsi:schemaLocation="http://symfony.com/schema/dic/services
1678+
https://symfony.com/schema/dic/services/services-1.0.xsd">
1679+
1680+
<services>
1681+
<!-- ... -->
1682+
1683+
<!-- Disable autoconfigure to prevent this normalizer from automatically -->
1684+
<!-- being included in the default serializer -->
1685+
<service
1686+
id="Symfony\Component\Serializer\Normalizer\CustomNormalizer"
1687+
autoconfigure="false"
1688+
>
1689+
<!-- Include this normalizer in a single serializer -->
1690+
<tag name="serializer.normalizer" serializer="api_client1"/>
1691+
1692+
<!-- Include this normalizer in multiple serializers -->
1693+
<tag name="serializer.normalizer" serializer="api_client1"/>
1694+
<tag name="serializer.normalizer" serializer="api_client2"/>
1695+
1696+
<!-- Include this normalizer in all serializers (including the default one) -->
1697+
<tag name="serializer.normalizer" serializer="*"/>
1698+
</service>
1699+
</services>
1700+
</container>
1701+
1702+
.. code-block:: php
1703+
1704+
// config/services.php
1705+
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
1706+
1707+
use Symfony\Component\Serializer\Normalizer\CustomNormalizer;
1708+
1709+
return function(ContainerConfigurator $container) {
1710+
// ...
1711+
1712+
$services->set(CustomNormalizer::class)
1713+
// Prevent this normalizer from automatically being included in the default serializer
1714+
->autoconfigure(false)
1715+
1716+
// Include this normalizer in a single serializer
1717+
->tag('serializer.normalizer', ['serializer' => 'api_client1'])
1718+
// Include this normalizer in multiple serializers
1719+
->tag('serializer.normalizer', ['serializer' => ['api_client1', 'api_client2']])
1720+
// Include this normalizer in all serializers (including the default one)
1721+
->tag('serializer.normalizer', ['serializer' => '*'])
1722+
;
1723+
};
1724+
1725+
When the ``serializer`` attribute is not set, the service is registered with
1726+
the default serializer.
1727+
1728+
Each normalizer and encoder used in a named serializer is tagged with
1729+
a ``serializer.normalizer.<name>`` or ``serializer.encoder.<name>`` tag,
1730+
which can be used to list their priorities using the following command:
1731+
1732+
.. code-block:: terminal
1733+
1734+
$ php bin/console debug:container --tag serializer.<normalizer|encoder>.<name>
1735+
1736+
Additionally, you can exclude the default set of normalizers and encoders by
1737+
setting the ``include_built_in_normalizers`` and ``include_built_in_encoders``
1738+
options to ``false``:
1739+
1740+
.. configuration-block::
1741+
1742+
.. code-block:: yaml
1743+
1744+
# config/packages/serializer.yaml
1745+
framework:
1746+
serializer:
1747+
named_serializers:
1748+
api_client1:
1749+
include_built_in_normalizers: false
1750+
include_built_in_encoders: true
1751+
1752+
.. code-block:: xml
1753+
1754+
<!-- config/packages/serializer.xml -->
1755+
<?xml version="1.0" encoding="UTF-8" ?>
1756+
<container xmlns="http://symfony.com/schema/dic/services"
1757+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1758+
xmlns:framework="http://symfony.com/schema/dic/symfony"
1759+
xsi:schemaLocation="http://symfony.com/schema/dic/services
1760+
https://symfony.com/schema/dic/services/services-1.0.xsd
1761+
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
1762+
1763+
<framework:config>
1764+
<framework:serializer>
1765+
1766+
<framework:named-serializer
1767+
name="api_client1"
1768+
include-built-in-normalizers="false"
1769+
include-built-in-encoders="true"
1770+
/>
1771+
1772+
</framework:serializer>
1773+
</framework:config>
1774+
</container>
1775+
1776+
.. code-block:: php
1777+
1778+
// config/packages/serializer.php
1779+
use Symfony\Config\FrameworkConfig;
1780+
1781+
return static function (FrameworkConfig $framework): void {
1782+
$framework->serializer()
1783+
->namedSerializer('api_client1')
1784+
->includeBuiltInNormalizers(false)
1785+
->includeBuiltInEncoders(true)
1786+
;
1787+
};
1788+
15401789
Debugging the Serializer
15411790
------------------------
15421791

0 commit comments

Comments
 (0)