Overriding Settings in Code with settings.local.php

Previous versions of Drupal have had the ability to override database variables with hard-coded values in the settings.php file. For example, in the Drupal 7 default.settings.php file, you'll find a section for "Variable overrides" where it shows how to override the site name by uncommenting the line "$conf['site_name'] = 'My Drupal site';".

Many site-builders took this a step further by including a settings.local.php file that would contain settings specific to one instance of the site. For example, the site name might be "Drupal 7" on the production server, but be "Drupal 7 (Dev)" on the development server, to help them know which one they were working on.

More common reasons to do this were to include configuration common to all instances of a site in settings.php (like the admin theme, or who can register accounts) and commit that file to the Git repository. Then, store instance-specific settings (like the database credentials and caching settings) in the settings.local.php file, and not commit that to the repository.

This is a super useful technique, because you can, for example, ensure that caching is always enabled on production, and never enabled on your development machine, without worrying about disabling it every time you pull the database down, or forgetting to enable it before you export config locally, or after you make a change directly on production.

There's good news and bad news for this technique in Drupal 8.

  • The good news: We can still do this in Drupal 8, and the technique is performed the same, though the variables have different names.
  • The bad news: Because Drupal 8 config is stored in files, we can't (at this time) see the overrides in the UI, like we could in Drupal 7. So, you have to know what you're doing, and verify each override manually.

Note: I say "at this time" because there is discussion happening in the issue queues at node/2408549. It might be worth reading through that issue, and providing your feedback!

Create settings.local.php

We actually created this file in an earlier video so that we could commit settings.php without the database info, but in case you're just jumping in at this point, creating the settings.local.php file is just as easy as it sounds. In the "web/sites/default" directory, create a file named settings.local.php.

I'll add one small change so that when the file is enabled, we'll know that it's working. I'll add "(Dev)" to the site name.

  • Edit the settings.local.php file and add the following:
 * Site Information
// Site Name
$config['system.site']['name'] = 'Drupal 8 Site (Dev)';

Now, let's review how to enable the settings.local.php file from within settings.php so that the settings we override with local ones will take effect.

Enable settings.local.php

If you open up your settings.php file, and scroll to the bottom, you'll find a section labeled "Load local development override configuration, if available.". This is what lets us use our settings.local.php file.

  • Uncomment the last three lines
if (file_exists(__DIR__ . '/settings.local.php')) {
  include __DIR__ . '/settings.local.php';

And again, note that the file says "Keep this code block at the end of this file to take full effect.". This is important, because anything below this code block will override our settings.local.php file, which defeats the point. So make sure it is the very last thing in settings.php.

Now, if I clear the cache and refresh my site, you'll notice the site name has changed and you'll see the "(Dev)" text. However, if I go to "Configuration => System => Basic site settings" (/admin/config/system/site-information) you won't see the change there. In Drupal 7, the overriding value was shown in the field, but because of the way Drupal 8 stores configuration to files, instead of the database, it can't show our overrides in the UI.

(For more info on configuration overrides, Check out node/1928898 on Drupal.org)

So, as I said before, it's a little annoying that we can't verify our overrides via the UI, but the benefit of the way Drupal 8 stores configuration in files (allowing configuration management to work so well) more than makes up for it.