Fixed: tagged services YAML example can be misleading

[romaricdrigon]

Hello,

At the moment, I find tagged services example in YAML to be misleading:

# config/services.yaml
services:
    App\HandlerCollection:
        # inject all services tagged with app.handler as first argument
        arguments: [!tagged app.handler]

[!tagged app.handler] means all tagged services, which is a RewindableGenerator, to be injected as the array of arguments. It combines both a syntax specific to injecting the array of arguments, and the !tagged app.handler syntax, to get an array of tagged services (moreover, which is a non-standard and uncommon syntax).

Having both syntax, both arrays, shown at the same time makes the snippet hard to grasp for newcomers.
We had the issue with a coworker a few minutes ago, he did this naively:

services:
    App\HandlerCollection:
        arguments: 
             - @router
             - @my_other_service
             - [!tagged app.handler]

And we lost some time to debug why we where getting an array of RewindableGenerator.

This PR simplifies YAML example to use a more common, more readable, and less risky to modify syntax:

services:
    App\HandlerCollection:
        arguments: 
            - !tagged app.handler

I think it will be clearer to newcomers.
I believe it also makes YAML example closer to XML example, since XML does not have a syntax for "array of all arguments passed to that service".

[stof]

the [] is just Yaml syntax for a sequence (an array indexed from 0 to length - 1, cf JS Array). It is not related to !tagged. YAML has 2 ways to define a sequence:

• the inline syntax [] (similar to the JS syntax)
• the nested syntax, with nested elements using -

services:
    App\HandlerCollection:
        arguments: [@router]

is exactly the same than

services:
    App\HandlerCollection:
        arguments:
            - @router

And after parsing the Yaml, we cannot even know which syntax was seen by the parser (which is totally expected).

note that the same is true for mappings (think about JS object literals). They also have an inline syntax (using { } and a nested syntax (with the keys indented).

so this is absolutely not a non-standard notation.

[ostrolucky]

I prefer short notation in case there is one argument only, like it is now. When using yaml, you need to know the yaml syntax and this error was good for your colleague to learn it

[romaricdrigon]

@stof I get that, and I understand []. I said !tagged xxx is not standard, not [].
My point is that mixing both makes the snippet less clear and easier to misunderstand, which is not great for beginners to Symfony/YAML.

@ostrolucky I can't help but feel it is a little bit unsensitive to say "people will learn the hard way".

[xabbuh]

I have no facts pointing out that either the inline or the nested notation are easier to understand. But I can see that copying a single argument is easier when using the nested notation. That would actually be an argument for me in of using it in favour of the inline notation.

[wouterj]

I agree with @xabbuh and @romaricdrigon here that the nested notation is easier to copy (and thus, at least, easier to use in your application when reading the docs). (also funny to see the GitHub parser understanding the tag in the nested example, but failing to do so in the inline variant).

We're getting in the weird zone of Yaml here though: - !tagged something looks really scary and would blow my mind when I would first see it in the docs. I guess there is not so much we can do here besides using the nested variant (maybe explain that !tagged is a Yaml tag. Anyway, 👍

[javiereguiluz]

Thank you Romaric.