Include a Local Drupal Settings file for Environment Configuration and Overrides

20th December 2014

Warning: This post is over a year old. I don't always update old posts with new information, so some of this information may be out of date.

How to create and include a local settings file to define and override environment-specific variables, and keep sensitive things like your database credentials and API keys safe.

At the bottom of settings.php, add the following code:

$local_settings = __DIR__ . '/settings.local.php';
if (file_exists($local_settings)) {
  include $local_settings;

This allows for you to create a new file called settings.local.php within a sites/* directory (the same place as settings.php), and this will be included as an extension of settings.php. You can see the same technique being used within Drupal 8's default.settings.php file.

Environment specific settings like $databases and $base_url can be placed within the local settings file. Other settings like $conf['locale_custom_strings_en'] (string overrides) and $conf['allow_authorize_operations'] that would apply to all environments can still be placed in settings.php.

settings.php though is ignored by default by Git by a .gitignore file, so it won't show up as a file available to be committed. There are two ways to fix this. The first is to use the --force option when adding the file which overrides the ignore file:

git add --force sites/default/settings.php

The other option is to update the .gitignore file itself so that settings.php is no longer ignored. An updated .gitignore file could look like:

# Ignore configuration files that may contain sensitive information.

# Ignore paths that contain user-generated content.

This will allow for settings.php to be added to Git and committed, but not settings.local.php.

Questions? Comments? I’m @opdavies on Twitter, or send me an email.


About the Author

Picture of Oliver

Oliver Davies is a full-stack Web Developer and System Administrator based in the UK. He is a Senior Developer at Microserve and a part-time freelancer specialising in Drupal, Symfony and Laravel development and Linux systems administration.