@@ -405,3 +405,126 @@ The double loop may be confusing. This is because a service can have more
405
405
than one tag. You tag a service twice or more with the ``app.mail_transport ``
406
406
tag. The second foreach loop iterates over the ``app.mail_transport ``
407
407
tags set for the current service and gives you the attributes.
408
+
409
+ Reference Tagged Services
410
+ ~~~~~~~~~~~~~~~~~~~~~~~~~
411
+
412
+ .. versionadded :: 3.4
413
+ Support for the tagged service notation in YAML, XML and PHP was introduced
414
+ in Symfony 3.4.
415
+
416
+ Symfony provides a shortcut to inject all services tagged with a specific tag,
417
+ which is a common need in some applications, so you don't have to write a
418
+ compiler pass just for that.
419
+
420
+ In the following example, all services tagged with ``app.handler `` are passed as
421
+ first constructor argument to the ``App\HandlerCollection `` service:
422
+
423
+ .. configuration-block ::
424
+
425
+ .. code-block :: yaml
426
+
427
+ # app/config/services.yml
428
+ services :
429
+ AppBundle\Handler\One :
430
+ tags : [app.handler]
431
+
432
+ AppBundle\Handler\Two :
433
+ tags : [app.handler]
434
+
435
+ AppBundle\HandlerCollection :
436
+ # inject all services tagged with app.handler as first argument
437
+ arguments : [!tagged app.handler]
438
+
439
+ .. code-block :: xml
440
+
441
+ <!-- app/config/services.xml -->
442
+ <?xml version =" 1.0" encoding =" UTF-8" ?>
443
+ <container xmlns =" http://symfony.com/schema/dic/services"
444
+ xmlns : xsi =" http://www.w3.org/2001/XMLSchema-instance"
445
+ xsi : schemaLocation =" http://symfony.com/schema/dic/services
446
+ http://symfony.com/schema/dic/services/services-1.0.xsd" >
447
+
448
+ <services >
449
+ <service id =" AppBundle\Handler\One" >
450
+ <tag name =" app.handler" />
451
+ </service >
452
+
453
+ <service id =" AppBundle\Handler\Two" >
454
+ <tag name =" app.handler" />
455
+ </service >
456
+
457
+ <service id =" AppBundle\HandlerCollection" >
458
+ <!-- inject all services tagged with app.handler as first argument -->
459
+ <argument type =" tagged" tag =" app.handler" />
460
+ </service >
461
+ </services >
462
+ </container >
463
+
464
+ .. code-block :: php
465
+
466
+ // app/config/services.php
467
+ use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;
468
+
469
+ $container->register(AppBundle\Handler\One::class)
470
+ ->addTag('app.handler');
471
+
472
+ $container->register(AppBundle\Handler\Two::class)
473
+ ->addTag('app.handler');
474
+
475
+ $container->register(AppBundle\HandlerCollection::class)
476
+ // inject all services tagged with app.handler as first argument
477
+ ->addArgument(new TaggedIteratorArgument('app.handler'));
478
+
479
+ After compilation the ``HandlerCollection `` service is able to iterate over your
480
+ application handlers.
481
+
482
+ .. code-block :: php
483
+
484
+ // src/AppBundle/HandlerCollection.php
485
+ namespace AppBundle;
486
+
487
+ class HandlerCollection
488
+ {
489
+ public function __construct(iterable $handlers)
490
+ {
491
+ }
492
+ }
493
+
494
+ .. tip ::
495
+
496
+ The collected services can be prioritized using the ``priority `` attribute:
497
+
498
+ .. configuration-block ::
499
+
500
+ .. code-block :: yaml
501
+
502
+ # app/config/services.yml
503
+ services :
504
+ AppBundle\Handler\One :
505
+ tags :
506
+ - { name: app.handler, priority: 20 }
507
+
508
+ .. code-block :: xml
509
+
510
+ <!-- app/config/services.xml -->
511
+ <?xml version =" 1.0" encoding =" UTF-8" ?>
512
+ <container xmlns =" http://symfony.com/schema/dic/services"
513
+ xmlns : xsi =" http://www.w3.org/2001/XMLSchema-instance"
514
+ xsi : schemaLocation =" http://symfony.com/schema/dic/services
515
+ http://symfony.com/schema/dic/services/services-1.0.xsd" >
516
+
517
+ <services >
518
+ <service id =" AppBundle\Handler\One" >
519
+ <tag name =" app.handler" priority =" 20" />
520
+ </service >
521
+ </services >
522
+ </container >
523
+
524
+ .. code-block :: php
525
+
526
+ // app/config/services.php
527
+ $container->register(AppBundle\Handler\One::class)
528
+ ->addTag('app.handler', array('priority' => 20));
529
+
530
+ Note that any other custom attributes will be ignored by this feature.
0 commit comments