While this will definitely enhance DI in certain conditions (parameters primarily), I'm afraid that the @service_id will be overlooked quite a bit. Right now, if I see a type-hinted docblock with @param while the signature in the constructor is already present, I will simply remove it. This might result in over-looked bugs because "it's only a comment". Don't get me wrong, I love annotations... It's just totally not what you expect the @param to be used for.

I like the idea because it's an out-of-the-box solution, but it still comes down to DI by annotation, which has been rejected in the past. The only difference is that it's not a custom annotation, but alters behavior of an existing annotation, which is not a good idea imo.

@javiereguiluz I'm not that familiar with docblocks, but if I recall correctly, it should be {@see ...} for nested annotations. Correct me if I'm wrong 😄

While bindings are writing DI config against code, to me this proposition is writing "code" against DI config (but I guess it depends the POV).

About using service identifiers: I used to consider them as pure ref-targets with no inherent semantic; i.e. random strings to target objects in the container. That's what they are for many ids. But I recently realized that service ids also convey a generic semantic that is broader than the container itself. [...]

We could debate a lot about that I guess. But it looks more like a pretext than a real argument to me. 😕
In case of the ServiceSubcriberInterface at least, the ids are really what the code expects to find in the injected service locator, so it's really part of the code. Here we're still referencing DI services directly to expect the proper service being injected, without any control.
So, in order to reverse a bit my "this proposition is writing code against DI config" predicate above, shouldn't this at least fail and throw an exception when trying to autowire a class with @param BusInterface $commandBus @bus.command and the corresponding service id does not exist?

You may have understood I'm not really convinced right now, but curious to see where this is going :)

Status: needs work

I'm putting this PR on-hold so that instead of targetting ids/parameters, we could leverage "semantics", as defined in #27207.
We'll also need to make this work with controller actions and service subscribers, which are the two other places that allow referencing services, each with a dedicated way to do so.

For the record and to answer @iltar's question, my idea is to allow referencing only "semantics" from these annotations. This would make it clear that we're not targetting a specific service, but only those that convey a generic and meaningful name. That would also allow to enforce the type of the target at compile time, and allow building nice error messages (eg "you cannot target service foo because it's not listed for FooInterface, here are the ones that are possible here: ...").

I think that this would conflict with this PR PHP-CS-Fixer/PHP-CS-Fixer#3734

It should only remove superfluous @param when there isn't a description associated to it. So it shouldn't be an issue for this.

I know it's been mentionned, but I'm kinda against that, as @ogizanagi said : it looks like you're coding against the DI. If you want to use the object outside, you have docblocs which are... superfluous and doesn't bring anything...

Adding this in docblock support is the same as having the proper di config, except that your code stays unaware of DI. Which should satisfy some principes of SOLID (here, it kinda violates IMO the dependency inversion...)

@nicolas-grekas are there some specific annotation parsers that are known to fail on new annotations? For me reusing @param seems a bit... ugly? Not to mention ambiguous and potentially dangerous, as we have no idea what comments are there already @param. Plus to add support for these annotations, editors might need to do significant amount of changes, to implement, for example highlighting etc.

Maybe it would pay to actually add a new, generic param to identify services, in this case, maybe something similar to @Named from Java? This would have numerous advantages.

Think something like this:

/**
 * @param Client $myFooBarClient
 * @param string $param
 * @param OtherService $bar totally autowired, no @named tags
 * @named Client @mycompany.connectors.foo.main_connector
 * @named string %some.param.maybe%
 */
public function __construct(Client $myFooBarClient, string $param, OtherService $bar)
{
}

Yes, a bit verbose. But for me, much better than mangling with @param

I really like the idea of adding such a concept and "semantics" is a name I could buy in. Though, I'm really not fond of the idea of using @param docs for this as it has already a huge history of pros/cons and associated benefits.

I'd prefer something that simulates Java-like annotations on method properties like the following:

public function __construct(
    /* @Semantics("event_bus") */ MessageBusInterface $eventBus,
    /* @Semantics("video_filesystem") */ FlysystemInterface $videoFilesystem
) {
    // ...
}

Disclaimer: I didn't dig in the faisibility of this but AFAIK PHP's reflection suite does not allow to get such comments (while it does for the method docblock).

Even with docblocks, I'm not sure if it stores argument docblocks at property or argument level though.

Having a proper annotation mechanism in PHP would be even better :)

Even with docblocks, I'm not sure if it stores argument docblocks at property or argument level though.

Correct but you can be pretty sure that it will be easy to deal with regexes.

Having a proper annotation mechanism in PHP would be even better :)

Such a thing could drive property annotations in PHP, who knows 🤷‍♂️

Closing in favor of #28234