Allow to tag services as "configurator" for other services.

All we need is a compiler pass. Proof of concept PR will follow :)

{ name: configurator, method: configureConsumer, target: configured_service }

The method and target could be optional.
Instead, a method attribute could be used.

class ConfiguratorService {
  #[Configurator(target: 'configured_service')]
  public function configureConsumer(ConfiguredService $service): void {
    $service->addHandler(new CustomObject(...));
    $service->setColor('blue');
  }
}

If the service id is a class or interface name, then the "target" parameter could be omitted, instead the target id would be "ConfiguredService" as the parameter type.

The mechanism would also allow decorators, if the parameter is by reference:
(Actually I am not sure if this is meant to be supported.)

class ConfiguratorService {
  public function configureConsumer(ConfiguredService &$service): void {
    $service = new ConfiguredServiceDecorator($service);
  }
}

donquixote → closed merge request !3917

(I did not like the branch name of the first MR)

34 | WARNING | Code after the THROW statement on line 30 cannot be
| | executed
| | (Squiz.PHP.NonExecutableCode.Unreachable)

        $method_name = $configurator_tag['method']
          ?? throw new LogicException(sprintf(
            "Missing 'method' key on 'configurator' service tag on '%s'.",
            $id,
          ));
        $target_id = $configurator_tag['target'] ?? NULL;

PhpCS does not like null coalesce + throw. Sad!

One possible flaw of this mechanism is that the "subscribers" or "configurators" are directly coupled to the specific service they configure, instead of just to a service tag.

This means when changing the configured service id or its configuration method signature, one also has to change all the configurator services.

I think this flaw is acceptable in situations where we only want to add a few configurators.

Ok, this is it for now :)
The mechanism works, there is a basic test.
If we want this we can improve and refine the details.

Obviously, the second PR with the 3357916-service-configurator-tag-proof-of-concept branch is _NOT_ what we want to merge.

My own current use case has changed, so for now I am going with a different solution.
And anyway, if I needed this urgently right now I would probably do it in custom or contrib code.

Lets get this in front of a committers eye.

Assuming if it gets green lit there will need to be a change record.

I am wary of adding this if we have no actual use case; given Symfony does not have this feature and @donquixote found another way in their own code, do we really need this in core?

I agree, we should put this on hold until we have more use cases.
The PR shows that it can be done, but this does not mean we have to.

I already looked into existing code in Drupal core, to find cases that could have been done with this feature.
There were some, but there was not the one super convincing example where it would make a significant difference.

Also, something similar can be achieved with the decorator feature:
You can register a decorator with a factory, and that factory, instead of creating a new instance wrapping the original instance, can simply call a setter method and return the old instance.

Marking as postponed to get this out of the RTBC queue; if anyone finds that this is useful to them please comment and we can consider it again for core.

@longwave thanks for taking a look!