Why you should care about using settings.local.php

Published February 6, 2024
Spotlight on the settings.local.php file in a list of files.

Teaching folks why a settings.local.php file is an important part of setting up a personal development environment is so important to us here at DrupalEasy that it is a foundational part of both of our long-form Drupal training courses.

While preparing for an upcoming podcast mini-series I've been invited to participate in with the Talking Drupal folks, I'll be mentoring someone who is looking to re-enter the Drupal development scene after missing out on Drupal's transition from its pre-Symfony days. One of the tasks I have outlined for this person is to set up a settings.local.php file. When I went to find a good resource for the "why" and the "how", I came up empty. I couldn't find a single, up-to-date resource that conveyed what I feel is important.

So, that's what this blog post is all about. 

Why use settings.local.php?

Using a settings.local.php is all about configuring your local development environment for a project to be as useful to you, the developer, as possible. Default settings in this file do things like force all errors to the screen and disabling some of the (but not all) Drupal caches.

This file also pulls in the sites/development.services.yml file which contains some useful service class parameters and overrides - again, things that are useful for local development.

Setting up a settings.local.php literally takes less than two minutes, and when I see a Drupal developer struggling to figure out a white-screen-of-death error on their local environment, I can't help but 🙄

In addition to adding Drupal's core-dev dependencies and the Devel module, enabling the settings.local.php file is literally one of the first things I do when setting up a new site.

How do I enable the settings.local.php?

I'm so glad you asked.

Step 1

Copy sites/example.settings.local.php to sites/default/settings.local.php. Use a user interface (like the MacOS Finder) or the command line - it doesn't matter.

cp web/sites/example.settings.local.php web/sites/default/settings.local.php

Step 2

Uncomment the conditional include for settings.local.php in your sites/default/settings.php file - it looks like this:

#  if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
#   include $app_root . '/' . $site_path . '/settings.local.php';
# }

Uncommented, it looks like this:

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
 include $app_root . '/' . $site_path . '/settings.local.php';

Step 3

There is no step 3. This blog post is complete. 


It would be great a post about the settings files (settings.php settings.ddev.php and settings.local.php) on each environments. I mean on local, dev, prod, etc. for instance to which files must be synchronized, whee I should place split config, etc. Thanks so much for sharing your experiences with all the community! Greetings from Argentina.

Submitted by Juan Pablo Fra… (not verified) on Tue, 02/06/2024 - 17:40

Oh darn. I was hoping to see some of your tips of the types of things you usually end up adding into your settings.local.php. I have a lot of my own standard things that get placed there, but I was hoping that I might pick up something new from your experience. Thanks!

Submitted by Guest (not verified) on Thu, 02/08/2024 - 09:43

Add new comment

Sign up to receive email notifications of whenever we publish a new blog post or quicktip!