The role(s) of services.yml files in Drupal

Most Drupal back-end developers, regardless of their skill level, have at least a passing knowledge of the role of services.yml files in Drupal development. While writing the curriculum for our upcoming, long-form Intermediate Module Development course, we realized that it only makes sense that we provide not only the purpose of a services.yml file when writing custom service classes, but also the role of both the sites/development.services.yml file and the sites/default/default.services.yml files. 

If you are already familiar with the process for creating a custom service class, then you know that the module_name.services.yml file serves to not only define the service name, class, and other service dependencies, but also parameters. One of the cool features of Drupal service classes is that parameters can be overridden in a way that customizes the service's behavior without modifying the module_name.services.yml file. 

Anyone who has done even a smidgen of front-end work in Drupal is probably aware of the process of enabling twig_debug by adding a bit of yml to (usually) the sites/development.services.yml file. What you may not be aware of is that this is exactly what we're talking about. twig_debug is just a parameter to the "twig" service class. 

If your (local) site is using the default settings.local.php file, then you might be aware that service (container) overrides can also be performed in the sites/development.services.yml file. This is because Drupal allows multiple service .yml files to be loaded at a time via the $settings['container_yamls'][] array.

In fact, there are generally two files that are used to override service class parameter values:

1. web/sites/development.services.yml - this is often used only during development, and is automatically parsed when the default settings.local.php is also being used. This is due to the inclusion of $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml'; in settings.local.php.
2. web/sites/default/services.yml - this file doesn't exist by default, normally it is created from web/sites/default/default.services.yml. When present, this is automatically parsed when the following is present in settings.php: $settings['container_yamls'][] = $app_root . '/' . $site_path . '/services.yml'; The default.services.yml file contains most of the service parameters from Drupal core's core.services.yml file.

Finally, it is important that care is used when using both development.services.yml and services.yml files at the same time. Generally, when overriding parameters, it is best to put all overrides in only one of these two files.

So then, which, if any, should you commit to the project repository? It is not recommended to ever commit development.services.yml - this should be treated the same way as settings.local.php. If you are making all-environment parameter changes, then it is best to make these in sites/default/services.yml (after copying from default.services.yml) and commit this file. 

Finally, note that some Drupal hosting companies (like Pantheon) have additional considerations and features for using services.yml files. 

If you find this helpful and are interested in learning more about Drupal module development, you may want to check out our Professional Module Development course. 

The pixel art image used in this blog post was generated by the DALL-E project of OpenAI.