diff --git a/core/lib/Drupal/Core/DependencyInjection/ContainerBuilder.php b/core/lib/Drupal/Core/DependencyInjection/ContainerBuilder.php index 56f1627..9c06053 100644 --- a/core/lib/Drupal/Core/DependencyInjection/ContainerBuilder.php +++ b/core/lib/Drupal/Core/DependencyInjection/ContainerBuilder.php @@ -15,6 +15,8 @@ * Drupal's dependency injection container builder. * * @todo Submit upstream patches to Symfony to not require these overrides. + * + * @ingroup container */ class ContainerBuilder extends SymfonyContainerBuilder { diff --git a/core/lib/Drupal/Core/DependencyInjection/ServiceModifierInterface.php b/core/lib/Drupal/Core/DependencyInjection/ServiceModifierInterface.php index 000366c..08c881e 100644 --- a/core/lib/Drupal/Core/DependencyInjection/ServiceModifierInterface.php +++ b/core/lib/Drupal/Core/DependencyInjection/ServiceModifierInterface.php @@ -4,6 +4,8 @@ /** * Interface that service providers can implement to modify services. + * + * @ingroup container */ interface ServiceModifierInterface { diff --git a/core/lib/Drupal/Core/DependencyInjection/ServiceProviderBase.php b/core/lib/Drupal/Core/DependencyInjection/ServiceProviderBase.php index c633395..49e9fbb 100644 --- a/core/lib/Drupal/Core/DependencyInjection/ServiceProviderBase.php +++ b/core/lib/Drupal/Core/DependencyInjection/ServiceProviderBase.php @@ -9,6 +9,8 @@ /** * Base service provider implementation. + * + * @ingroup container */ abstract class ServiceProviderBase implements ServiceProviderInterface, ServiceModifierInterface { diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php index 02c1cea..323f60a 100644 --- a/core/modules/system/core.api.php +++ b/core/modules/system/core.api.php @@ -658,14 +658,118 @@ /** * @defgroup container Services and Dependency Injection Container * @{ - * Overview of the Dependency Injection Container and Services. - * - * @todo write this - * - * Additional documentation paragraphs need to be written, and functions, - * classes, and interfaces need to be added to this topic. + * Information about the Dependency Injection Container and Services. + * + * @section sec_overview Overview of container, injection, and services + * The Services and Dependency Injection Container concepts have been adopted by + * Drupal from the @link http://symfony.com/ Symfony framework. @endlink A + * "service" (such as accessing the database, sending email, or translating user + * interface text) can be defined by Drupal Core or a module, along with a + * default class for providing that service. Other modules can offer alternative + * classes to provide the same services, overriding the default classes. Classes + * and functions that need to use the service should always instantiate the + * class via the "dependency injection container" (also known simply as the + * "container"), rather than instantiating a particular service provider class + * directly, so that they get the correct class (default or overridden). + * + * See https://drupal.org/node/2133171 for more detailed information on + * services and the dependency injection container. + * + * @section sec_discover Discovering existing services + * Drupal core defines many core services in the core.services.yml file (in the + * top-level core directory). Some Drupal Core modules and contributed modules + * also define services in modulename.services.yml files. API reference sites + * (such as https://api.drupal.org) generate lists of all existing services from + * these files, or you can look through the individual files manually. + * + * A typical service definition in a services.yml file looks like this: + * @code + * path.alias_manager: + * class: Drupal\Core\Path\AliasManager + * arguments: ['@path.crud', '@path.alias_whitelist', '@language_manager'] + * @endcode + * The first line gives the machine name of the service, and the class line + * gives the default class that provides the service. For some services, the + * arguments line lists other services that are dependencies; the classes + * for each of these services is instantiated from the container and passed + * to the class constructor when the service class is instantiated. + * + * @section sec_container Accessing a service through the container + * As noted above, if you need to use a service in your code, you should always + * instantiate the service class via a call to the container, so that the + * default class can be overridden. There are several ways to make sure this + * happens: + * - For service-providing classes, see other sections of this documentation + * describing how to pass services as arguments to the constructor. + * - Plugin classes, controllers, and similar classes have create() methods, + * whose first argument is + * @code + * \Symfony\Component\DependencyInjection\ContainerInterface $container + * @endcode + * In the create() method, call + * @code $container->get('service.name') @endcode to instantiate a service. + * The results of these calls are generally passed to the class constructor + * and saved as member variables in the class. + * - For functions and class methods that do not have access to either of + * the above methods of "dependency injection", you can access the container + * via a call to the global \Drupal class. This class has special methods for + * accessing commonly-used services, or you can call a generic method to + * access any service. Examples: + * @code + * // Retrieve the entity.manager service class (special method exists). + * $manager = \Drupal->entityManager(); + * // Retrieve the foo.bar service class (no special method exists). + * $foobar = \Drupal->service('foo.bar'); + * @endcode + * + * @section sec_define Defining a service + * If your module needs to define a new service, here are the steps: + * - Choose a unique machine name for your service. Typically, this should + * start with your module name. Example: mymodule.myservice. + * - Create a PHP interface to define what your service does. + * - Create a default class implementing your interface that provides your + * service. If your class needs to use existing services (such as database + * access), be sure to make these services arguments to your class + * constructor, and save them in member variables. Also, if the needed + * services are provided by other modules and not Drupal Core, you'll want + * these modules to be dependencies of your module. + * - Add an entry to a modulename.services.yml file for the service. See + * @ref sec_discover above, or existing services.yml files in Core, for the + * syntax; it will start with your machine name, refer to your default class, + * and list the services that need to be passed into your constructor. + * + * @section sec_injection Overriding the default service class + * Modules can override the default classes used for services. Here are the + * steps: + * - Define a class in the top-level namespace for your module + * (Drupal\my_module), whose name is the camel-case version of your module's + * machine name followed by "ServiceProvider" (for example, if your module + * machine name is my_module, the class must be named + * MyModuleServiceProvider). + * - The class needs to implement + * \Drupal\Core\DependencyInjection\ServiceModifierInterface, which is + * typically done by extending + * \Drupal\Core\DependencyInjection\ServiceProviderBase. + * - Include a use statement for the class + * \Drupal\Core\DependencyInjection\ContainerBuilder + * - The class needs to contain one method: alter(). This method does the + * actual work of telling Drupal to use your class instead of the default. + * Here's an example: + * @code + * public function alter(ContainerBuilder $container) { + * // Override the language_manager class with a new class. + * $definition = $container->getDefinition('language_manager'); + * $definition->setClass('Drupal\my_module\MyLanguageManager'); + * } + * @endcode + * + * @see https://drupal.org/node/2133171 + * @see core.services.yml + * @see \Drupal + * @see \Symfony\Component\DependencyInjection\ContainerInterface + * @see plugin_api + * @see menu * - * See https://drupal.org/node/2133171 * @} */