Service container

The service container is the object that knows every service on a Drupal site and builds each one when code asks for it. Drupal collects the service definitions from modules and settings, compiles them once into a single definition, caches that result, and hands out one shared instance per service unless a definition says otherwise. The container is what turns a line in a services file into a working object.

How the container is built in Drupal 11

The Drupal kernel, DrupalKernel, builds the container in stages. This describes the 11.4.10 code.

1. Discovery. The kernel adds core/core.services.yml and the CoreServiceProvider class. For each enabled module it adds MODULE.services.yml and, if one exists, a class named after the module, such as MyModuleServiceProvider. Site files listed in $settings['container_yamls'] come last.
2. Registration. The YAML is loaded and each provider's register() method runs. Site-level files and providers load after the app ones, so they can override.
3. Compilation. Compiler passes process the definitions. Tags such as event_subscriber and cache.bin are collected here, because a tag does nothing on its own until a pass acts on it. A provider that implements ServiceModifierInterface can change definitions in alter().
4. Caching. The kernel dumps the result to an array and stores it in the container cache bin. The cache key includes a hash of the installed Composer package versions (or the Drupal version when the Composer scaffold has not generated that hash), the deployment_identifier setting, the operating system and the container_yamls list.

On later requests the kernel loads the cached definition instead of compiling. A service is created the first time something requests it, and it is shared by default, so every consumer gets the same object. The drupal_flush_all_caches() function invalidates the cached container and rebuilds it, which is what a full cache rebuild does.

One newer detail matters to developers. In 11.4.10 the HookCollectorPass compiler pass finds classes in a module's Hook namespace whose class or methods carry the #[Hook] attribute and registers them as autowired services. The class marks itself internal. Because that registration happens while the container is compiled, a new hook class is not picked up until the container is rebuilt; see hook system.

Example

Core ships default.services.yml as a template. Copy it to sites/default/services.yml, and the container picks it up through container_yamls. The template contains the container parameter security.enable_super_user. Its comment advises setting it to false when the site has at least one user with the Administrator role, so that user 1 can be made a regular user.

parameters:
          security.enable_super_user: false

Save the file and run drush cr. The next request compiles a container with the new parameter value.

Common mistakes

• Overriding part of an array parameter. Core merges service files shallowly. To change one value inside a parameter such as twig.config, copy the whole parameter from the default file, as the comment in development.services.yml says.
• Serializing the container. The core container class triggers an assertion if it is serialized. Classes that must survive serialization use DependencySerializationTrait and store service IDs, not the container.
• Leaving development parameters on. The default services file marks Twig debugging as not recommended for production.

For marketing and content teams

You never touch the container, but you may hear that a change "needs a cache rebuild". This is why: Drupal builds the container once and reuses it, so developer changes to services, hooks and some settings appear only after the rebuild. Ask for the rebuild to be part of every deploy. The first request after a rebuild compiles the container again. For the building blocks, read Services API and dependency injection.

Sources

• Services and Dependency Injection Container topic, core.api.php, Drupal 11.4.10
• DrupalKernel, Drupal 11.4.10 source
• CoreServiceProvider, Drupal 11.4.10 source
• HookCollectorPass, Drupal 11.4.10 source
• Core Container class, Drupal 11.4.10 source
• Component Container, Drupal 11.4.10 source
• default.services.yml, Drupal 11.4.10 source
• Drush cache:rebuild command