8000 Merge branch '4.4' into 5.1 · symfony/symfony-docs@7a820e3 · GitHub
[go: up one dir, main page]
Skip to content

Commit 7a820e3

Browse files
wouterjwouterj
committed
Merge branch '4.4' into 5.1
* 4.4: [#12697] Some minor tweaks [DependencyInjection] Add docs for default priority method for tagged services [#12461] Added versionadded directive List CSV encoder's context options
2 parents d5448d5 + 8a7d32e commit 7a820e3

File tree

2 files changed

+150
-33
lines changed

2 files changed

+150
-33
lines changed

‎components/serializer.rst

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -738,7 +738,7 @@ There are several types of normalizers available:
738738

739739
:class:`Symfony\\Component\\Serializer\\Normalizer\\ProblemNormalizer`
740740
Normalizes errors according to the API Problem spec `RFC 7807`_.
741-
741+
742742
.. _component-serializer-encoders:
743743

744744
Encoders
@@ -1214,6 +1214,52 @@ These are the options available:
12141214
``remove_empty_tags``
12151215
If set to true, removes all empty tags in the generated XML (default: ``false``).
12161216

1217+
The ``CsvEncoder``
1218+
------------------
1219+
1220+
This encoder transforms arrays into CSV and vice versa.
1221+
1222+
Context
1223+
~~~~~~~
1224+
1225+
The ``encode()`` method defines a third optional parameter called ``context``
1226+
which defines the configuration options for the CsvEncoder an associative array::
1227+
1228+
$csvEncoder->encode($array, 'csv', $context);
1229+
1230+
These are the options available:
1231+
1232+
``csv_delimiter``
1233+
Sets the field delimiter separating values (one character only, default: ``,``).
1234+
1235+
``csv_enclosure``
1236+
Sets the field enclosure (one character only, default: ``"``).
1237+
1238+
``csv_escape_char``
1239+
Sets the escape character (at most one character, default: empty string).
1240+
1241+
``csv_key_separator``
1242+
Sets the separator for array's keys during its flattening (default: ``.``).
1243+
1244+
``csv_headers``
1245+
Sets the headers for the data (default: ``[]``, inferred from input data's keys).
1246+
1247+
``csv_escape_formulas``
1248+
Escapes fields containg formulas by prepending them with a ``\t`` character (default: ``false``).
1249+
1250+
``as_collection``
1251+
Always returns results as a collection, even if only one line is decoded.
1252+
1253+
``no_headers``
1254+
Disables header in the encoded CSV (default: ``false``).
1255+
1256+
``output_utf8_bom``
1257+
Outputs special `UTF-8 BOM`_ along with encoded data (default: ``false``).
1258+
1259+
.. versionadded:: 4.4
1260+
1261+
The ``output_utf8_bom`` option was introduced in Symfony 4.4.
1262+
12171263
Handling Constructor Arguments
12181264
------------------------------
12191265

@@ -1468,6 +1514,7 @@ Learn more
14681514
.. _YAML: https://yaml.org/
14691515
.. _CSV: https://tools.ietf.org/html/rfc4180
14701516
.. _`RFC 7807`: https://tools.ietf.org/html/rfc7807
1517+
.. _`UTF-8 BOM`: https://en.wikipedia.org/wiki/Byte_order_mark
14711518
.. _`Value Objects`: https://en.wikipedia.org/wiki/Value_object
14721519
.. _`API Platform`: https://api-platform.com
14731520
.. _`list of PHP timezones`: https://www.php.net/manual/en/timezones.php

‎service_container/tags.rst

Lines changed: 102 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -585,47 +585,117 @@ application handlers::
585585
}
586586
}
587587

588-
.. tip::
588+
Tagged Services with Priority
589+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
590+
591+
.. versionadded:: 4.4
592+
593+
The ability to prioritize tagged services was introduced in Symfony 4.4.
594+
595+
The tagged services can be prioritized using the ``priority`` attribute,
596+
thus providing a way to inject a sorted collection of services:
597+
598+
.. configuration-block::
599+
600+
.. code-block:: yaml
589601
590-
The collected services can be prioritized using the ``priority`` attribute:
602+
# config/services.yaml
603+
services:
604+
App\Handler\One:
605+
tags:
606+
- { name: 'app.handler', priority: 20 }
607+
608+
.. code-block:: xml
609+
610+
<!-- config/services.xml -->
611+
<?xml version="1.0" encoding="UTF-8" ?>
612+
<container xmlns="http://symfony.com/schema/dic/services"
613+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
614+
xsi:schemaLocation="http://symfony.com/schema/dic/services
615+
https://symfony.com/schema/dic/services/services-1.0.xsd">
591616
592-
.. configuration-block::
617+
<services>
618+
<service id="App\Handler\One">
619+
<tag name="app.handler" priority="20"/>
620+
</service>
621+
</services>
622+
</container>
593623
594-
.. code-block:: yaml
624+
.. code-block:: php
595625
596-
# config/services.yaml
597-
services:
598-
App\Handler\One:
599-
tags:
600-
- { name: 'app.handler', priority: 20 }
626+
// config/services.php
627+
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
601628
602-
.. code-block:: xml
629+
use App\Handler\One;
603630
604-
<!-- config/services.xml -->
605-
<?xml version="1.0" encoding="UTF-8" ?>
606-
<container xmlns="http://symfony.com/schema/dic/services"
607-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
608-
xsi:schemaLocation="http://symfony.com/schema/dic/services
609-
https://symfony.com/schema/dic/services/services-1.0.xsd">
631+
return function(ContainerConfigurator $configurator) {
632+
$services = $configurator->services();
610633
611-
<services>
612-
<service id="App\Handler\One">
613-
<tag name="app.handler" priority="20"/>
614-
</service>
615-
</services>
616-
</container>
634+
$services->set(One::class)
635+
->tag('app.handler', ['priority' => 20])
636+
;
637+
};
617638
618-
.. code-block:: php
639+
Another option, which is particularly useful when using autoconfiguring
640+
tags, is to implement the static ``getDefaultPriority()`` method on the
641+
service itself::
619642

620-
// config/services.php
621-
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
643+
// src/Handler/One.php
644+
namespace App/Handler;
622645

623-
return function(ContainerConfigurator $configurator) {
624-
$services = $configurator->services();
646+
class One
647+
{
648+
public static function getDefaultPriority(): int
649+
{
650+
return 3;
651+
}
652+
}
625653

626-
$services->set(App\Handler\One::class)
627-
->tag('app.handler', ['priority' => 20])
628-
;
629-
};
654+
If you want to have another method defining the priority, you can define it
655+
in the configuration of the collecting service:
630656

631-
Note that any other custom attributes will be ignored by this feature.
657+
.. configuration-block::
658+
659+
.. code-block:: yaml
660+
661+
# config/services.yaml
662+
services:
663+
App\HandlerCollection:
664+
# inject all services tagged with app.handler as first argument
665+
arguments:
666+
- !tagged_iterator { tag: app.handler, default_priority_method: getPriority }
667+
668+
.. code-block:: xml
669+
670+
<!-- config/services.xml -->
671+
<?xml version="1.0" encoding="UTF-8" ?>
672+
<container xmlns="http://symfony.com/schema/dic/services"
673+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
674+
xsi:schemaLocation="http://symfony.com/schema/dic/services
675+
https://symfony.com/schema/dic/services/services-1.0.xsd">
676+
<services>
677+
<service id="App\HandlerCollection">
678+
<argument type="tagged" tag="app.handler" default-priority-method="getPriority"/>
679+
</service>
680+
</services>
681+
</container>
682+
683+
.. code-block:: php
684+
685+
// config/services.php
686+
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
687+
688+
use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;
689+
690+
return function (ContainerConfigurator $configurator) {
691+
$services = $configurator->services();
692+
693+
// ...
694+
695+
$services->set(App\HandlerCollection::class)
696+
->args([
697+
tagged_iterator('app.handler', null, null, 'getPriority'),
698+
]
699+
)
700+
;
701+
};

0 commit comments

Comments
 (0)
0