How to use settings.php

The scaffolding process will add a pre-populated settings.php file. Settings defined in this file are defaults set by ITS that should work for most sites, and the file is used by ITS to deploy important changes to sites. Developers should not directly modify this file, but rather should use context-specific PHP includes to override or supplement these defaults (shown below).

A site-specific file can be added and committed to your codebase so that it is present in testing and production environments. This should contain configuration settings that should be present in all environments or that should function differently between environments. The below example demonstrates how SMTP mail can be disabled in all cases except the live environment:

// The following disables email notifications in non-Pantheon environments.
if (!isset($_ENV['PANTHEON_ENVIRONMENT']) || $_ENV['PANTHEON_ENVIRONMENT'] !== 'live') {
  $config['smtp.settings']['smtp_on'] = FALSE;
  $config['system.mail']['interface']['default'] = 'test_mail_collector';
  $config['smtp.settings']['smtp_username'] = '';
  $config['smtp.settings']['smtp_password'] = '';

See also:


A settings.local.php can be added but should not be committed to your codebase (i.e., it should be in your .gitignore file), so that it only affects your development environment. A model for this file, demonstrating how it adds tooling specific to Docksal, can be found at

During development, it’s common to change which services.yml file is used to temporarily disable caching or enable Twig theme debugging. A good strategy for doing this is to copy the file provided in web/sites/ into web/sites/default/, and then add the following line to your settings.local.php file:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/default/';

The can then be committed to version control for your site and be ready when you need it in the future.