[DI] add syntax to stack decorators

[nicolas-grekas]

Q	A
Branch?	master
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	Fix #30599
License	MIT
Doc PR	-

Declare this:

services:
    my_stack_of_decorators:
        stack:
            - class: App\ExternalDecorator
            - class: App\InternalDecorator
            - class: App\DecoratoredClass

And get this:

The PR is now ready with support for Yaml, XML and the PHP-DSL. It needs #36388, #36392 and #36389 to pass, and relates to #36390 to be DX-friendly.

The new syntax now supports composable stacks - i.e stack you can reuse in the middle of another stack.

RIP middleware, simple decorators FTW :)

From the test cases:

services:
    reusable_stack:
        stack:
            - class: stdClass
              properties:
                  label: A
                  inner: '@.inner'
            - class: stdClass
              properties:
                  label: B
                  inner: '@.inner'

    concrete_stack:
        stack:
            - parent: reusable_stack
            - class: stdClass
              properties:
                  label: C

This will create a service similar to:

(object) [
    'label' => 'A',
    'inner' => (object) [
        'label' => 'B',
        'inner' => (object) [
             'label' => 'C',
        ]
    ],
];

When used together with autowiring, this is enough to declare a stack of decorators:

services:
    my_processing_stack:
        stack:
            - App\ExternalDecorator: ~
            - App\InternalDecorator: ~
            - App\TheDecoratedClass: ~

See fixtures for the other configuration formats.

See also https://twitter.com/nicolasgrekas/status/1248198573998604288

Todo:

• rebase on top of [DI] deprecate the inline() function from the PHP-DSL in favor of service() #36388, [DI] add missing property declarations in InlineServiceConfigurator #36392 and [DI] allow decorators to reference their decorated service using the special .inner id #36389 once they are merged
• test declaring deeper nested stacks

[dragoonis]

can you share details on why the community would switch from middleware to decorator stack pattern?

[nicolas-grekas]

@dragoonis everyone in the community will decide what they need, there is no one-size-fits-all solution. But this PR fills the gap between a middleware system and a stack of decorators. This brings "ease of stacking" to both styles. If that was the main benefit of a middleware system, this PR makes it less relevant - for ppl using the Symfony DI component of course.

See this thread for more details: https://twitter.com/nicolasgrekas/status/1248198573998604288

[jeremyFreeAgent]

Today I do that stack part by myself. Can’t wait to use it that way.

[nicolas-grekas]

This PR is ready and I'm quite happy about it!

Here are some implementation details and a future opening:

How does this work?

When a stack foo is declared, loaders create a ChildDefinition with the chain of decorators set as its arguments. The child definition is also tagged with a new container.stack tag. Like aliases, stacks support two attributes: public and deprecated.

This means it's possible to define a stack without using a loader, by following the above convention (all other attributes of the ChildDefinition would be ignored). The benefit of using a new syntax is that it makes defining the chain compatible with "defaults" set in the config file.

About the chain itself, it must be a list of either services, aliases or references. Alias and references are used undifferentiated to insert another stack definition in the middle of a new one. Both styles are needed to fit each kind of loader (yaml&xml can do only aliases and php-dsl does ref()).

This is already quite powerful. But there's more!

There's a second way to insert a stack inside a stack: using a "parent" in the chain. Such an insertion point will override the top-most definition in the embedded stack. This means one can also configure a stack while including it! All attributes of child definitions work here, it all depends on what the stack is about and only you will know about this.

Then, the new ResolveDecoratorStackPass will turn all this into plain old decorating services.

What could come next?

I've been talking with @dunglas and @pamil on Twitter and Slack and they asked me about inserting or removing frames inside an existing stack.

For now, this would be reasonably easy using a compiler pass.

Using configuration, we could also imagine new tags. E.g. one to allow filtering a frame while embedding a stack, another to allow replacing a frame by a new one, another for inserting a frame before/after another one - doing so either while embedding and/or by altering an existing stack definition. I didn't mention it, but frames can be named, this could help.

All this could replace an event dispatcher in some situations I believe. But that's hypotheses for the future.

Please give this a try for now :)

[fabpot]

Thank you @nicolas-grekas.