Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Split-up issue from #1875086: Improve DX of drupal_container()->get(), see #32, #36 and others.
We should define the concepts of how to use the container and add services to it through a bundle. Doesn't need to be detailed, we can link to symfony documentation for the generic parts. We should also add the kernel, CoreBundle, possibly some compiler passes and I think some of the interfaces to it that are defined as a service with @ingroup.
Automating the services export would be tricky I think because api.module does not have an installation and therefore can't call the container methods.
Comments
Comment #1
jhodgdonYou are correct - we can't rely on api.drupal.org being able to load any code (the site is currently running D6 and should soon be updated to D7 but it will be ages before it is running D8).
But it can collect doc blocks with certain tags in them... what did you have in mind?
Comment #2
sunA @defgroup is not compatible with decoupled services and components, because the corresponding @ingroup or @addtogroup would inherently add undesired coupling.
I'd recommend a generic annotation directive on all services that merely denotes the service ID:
1) @service on its own puts the class into a page that lists all classes tagged with @service.
2) The (optional) service container ID additionally outputs the (default) name of the service in Drupal's service container.
Comment #3
tim.plunkettOooh, @service sounds very very helpful to me!
Comment #4
BerdirWhy is a @defgroup not compatible with decoupled services?
What I mean is a @defgroup services to define the concept and API of the container itself, just like we have one for the form API and database API and so on :)
But yes, I was thinking about @service name resulting in a list/page with all services (similar to the existing lists of classes, files, functions, .. I guess) as well, which could be linked to from the services @defgroup :)
Comment #5
sunAny component in Drupal\Component potentially contains a class that is registered as a service. We would add @ingroup on that class. But all components in Drupal\Component are supposed to be completely decoupled from Drupal and thus re-usable in other code and applications. Therefore, "@ingroup foo" can have completely wrong and invalid effects within a code-base that is not Drupal.
Arguably, @service could equally have unintended effects, but that's a custom/non-standard phpDoc directive.
Comment #6
Crell CreditAttribution: Crell commentedThe trick with @service is that it can also be misleading. It is at best "as of when I wrote this class I expected it to probably get used at this service ID". That's as much of a guarantee as it offers, and any reasonably interesting Drupal site is going to have false negatives or false positives in that. Hell, even just in core we have 2-3 cache backends, and 8 or so service IDs that could be configured to use any of those classes, and that's before we start adding contrib implementations of Mongo, Memcache, or whatever. So what would you put for @service on Cache\DatabaseBackend?
Comment #7
Berdir@Crell: The @service tag would be added to the interface that a service provides, or the factory class that returns it. So I don't really get your argument. A different implementation is just a different implementation, it still provides the same methods, otherwise the whole thing would not work anyway? When developing a module and using the cache service, I don't care if it uses the database or memcache backend, I just want to know what the argument order was again for the set method.
Multiple services like cache is a bit of a problem, but as it is just a string, we could also easily define something like "@service cache.%bin" or a similar placeholder.
Comment #8
jhodgdonI like the idea of @service (name) being added to the class(es) that Drupal sets up as the default one(s) for a particular service name. Contrib modules could use the same tag. I don't see a problem with their being multiple classes marked with the same @service name -- that would, IMO, be a good thing, as people could see that multiple possibilities exist.
I would also like to see a @defgroup that would have some text to explain what "services" are, and maybe it could have a special tag @servicelist in it, so that the API module would know "This is where to put that list of services you are compiling". This @defgroup would go into some Drupal-specific file.
Comment #9
jhodgdonIf we're going to have a @service tag in docs, this is a standards issue...
Comment #10
jhodgdonWe've taken care of this documentation in other ways on other issues by now.