Create a settings.local.php file for Drupal development

To enable development specific functions and configuration, create a local settings file.

The default settings.php file contains information from your installation setup about your database and site environment. When developing, some of the settings from your production environment will not be the same as in development. We will create a settings.local.php file that won't get synced to the other environments such as production.

Here are some of the configuration items that would be different in Development that we'll store in our file.

  • Database information
  • Javascript and CSS caching and aggregation
  • twig/template debugging

From our project directory, copy the default setting.local.php for development provided by Drupal as an example. It's located at /web/sites/example.settings.local.php.

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

Let's open the file and take a look:

coda web/sites/default/settings.local.php

The first thing we see is a new file imported into the $settings configuration

/**
 * Enable local development services.
 */
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

This developoment services file includes yaml configuration geared towards development only. The first thing that can be enabled is twig debugging and that is done within the development.services.yml file that we just included in our local settings. Edit the development.services.yml file:

coda web/sites/development.services.yml

Add lines to the parameters section to enable twig debugging:

# Local development services.
#
# To activate this feature, follow the instructions at the top of the
# 'example.settings.local.php' file, which sits next to this file.
parameters:
  http.response.debug_cacheability_headers: true
services:
  cache.backend.null:
    class: Drupal\Core\Cache\NullBackendFactory

So that the content above looks now looks like this:

# Local development services.
#
# To activate this feature, follow the instructions at the top of the
# 'example.settings.local.php' file, which sits next to this file.
parameters:
  http.response.debug_cacheability_headers: true
  twig.config:
    debug: true
    auto_reload: true
    cache: false
services:
  cache.backend.null:
    class: Drupal\Core\Cache\NullBackendFactory

Include settings.local.php in settings.php

So far we've created the new local settings file settings.local.php, but it's still not included in the settings file being used by Drupal. To do that, open settings.php and scroll to the bottom. There will be a section that looks like this:

/**
 * Load local development override configuration, if available.
 *
 * Use settings.local.php to override variables on secondary (staging,
 * development, etc) installations of this site. Typically used to disable
 * caching, JavaScript/CSS compression, re-routing of outgoing emails, and
 * other things that should not happen on development and testing sites.
 *
 * Keep this code block at the end of this file to take full effect.
 */
#
# if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
#   include $app_root . '/' . $site_path . '/settings.local.php';
# }
$databases['default']['default'] = array (
  'database' => 'MYDBNAME',
  'username' => 'root',
  'password' => '*****',
  'prefix' => '',
  'host' => '127.0.0.1',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
);
$settings['config_sync_directory'] = 'sites/default/files/config_RRvZBvqpBR2OCtEkrdRJWCQo0KLjY7Vz8lwvPvlpqR4xE0LK97MEAyrtxHWfiyQMe_3pHfgT5g/sync';

If you read the comments it will explain that we need to uncomment the last lines of code before the database settings. We'll do that and then move the database setting to our local.settings.php file since they will be different than our production environment. We'll change the section so it looks like this:

/**
 * Load local development override configuration, if available.
 *
 * Use settings.local.php to override variables on secondary (staging,
 * development, etc) installations of this site. Typically used to disable
 * caching, JavaScript/CSS compression, re-routing of outgoing emails, and
 * other things that should not happen on development and testing sites.
 *
 * Keep this code block at the end of this file to take full effect.
 */

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

$settings['config_sync_directory'] = 'sites/default/files/config_RRvZBvqpBR2OCtEkrdRJWCQo0KLjY7Vz8lwvPvlpqR4xE0LK97MEAyrtxHWfiyQMe_3pHfgT5g/sync';

Please note the last line $settings['config_sync_directory'] =  

We won't address this here, but it can remain in the settings.php file. By default, when Drupal is installed, it creates a 'config_sync_directory' within the Drupal file system in sites/default/files. It uses a random folder name for this sync folder to keep it private. If you have not edited this setting it will look similar to what's shown here. Refer to the article "Importing and Exporting environment specific Configuration in Drupal” for more information.

Now we'll edit the settings.local.php file and add our database settings to the top.

coda web/sites/default/settings.local.php

The top of the file will then look like this:

<?php
  
$databases['default']['default'] = array (
  'database' => 'MYDBNAME',
  'username' => 'root',
  'password' => '*****',
  'prefix' => '',
  'host' => '127.0.0.1',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
);

// @codingStandardsIgnoreFile

And since it's imported into settings.php along with the rest of it we can now have environment specific settings by excluding this file from our version control and mailing separate settings.local.php files in each environment.

Add new comment

comment editor

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type='1 A I'> <li> <dl> <dt> <dd> <h2 id='jump-*'> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.