Document somewhat the session_bag tag

Problem/Motivation

For our site, we wanted to create a new service very similar to the messenger service, which is defined in core.services.yml as follows:

  messenger:
    class: Drupal\Core\Messenger\Messenger
    arguments: ['@session.flash_bag', '@page_cache_kill_switch']

Our custom service needed to use a separate FlashBag. The session.flash_bag service is also in core.services.yml:

  session.flash_bag:
    class: Symfony\Component\HttpFoundation\Session\Flash\FlashBag
    public: false

Looking at this, you would think that you could just make a new service called something like mymodule.flash_bag. However, if you do you will find that it doesn't work. The reason is that the session service is defined like this:

  session:
    class: Symfony\Component\HttpFoundation\Session\Session
    arguments: ['@session_manager', '@session.attribute_bag', '@session.flash_bag']
    tags:
      - { name: service_collector, tag: session_bag, call: registerBag }

The session.flash_bag service gets special treatment: it is passed into the constructor of Session. If you want to define an additional FlashBag, you need to tag it with the session_bag tag so the session service persists it between page loads. No other service uses FlashBag and none at all uses the session_bag tag so there's no example to copy.

Steps to reproduce

Proposed resolution

Add a note to session.flash_bag that if you want to add more flash bags, they need to be tagged with the session_bag tag.

Remaining tasks

Add documentation to core.services.yml

User interface changes

None.

API changes

None.

Data model changes

None.

Release notes snippet

None needed.