Skip to content

Setting layers

Where the value of a site's setting comes from, and how to pin one on a server.

The layers

A setting takes its value from the highest layer that sets one:

Layer Set on
settings.php the server, see below
Environment the section's Environments tab
Language the section's Translate tab
Site value the section's Edit tab
Site type default the type's matrix, Default and Default settings
Module default the module that adds the setting

The site type decides which layers a setting has: a site value only where the row is Available, an environment value only with Environment overrides, a language value only with Translatable. A value for one language in one environment wins over both.

The tabs of a section

Each settings section of a site, like Site information or Appearance, edits one layer per tab:

  • Edit: the site's own values.
  • Translate: one language's values. It shows when the Language module is installed, the site speaks more than one language and the type makes one of the section's settings Translatable.
  • Environments: one environment's values, with each environment listed as Inherited or Overridden. It shows when an environment besides the default exists and the type allows Environment overrides for one of the section's settings.

A field shows the value in effect for its layer and names where an inherited value comes from. Saving stores only what differs from the layer below. See Site settings for editing.

Environments

Environments come from the Environment context module, which Sites requires. With environment_context_config_split, each Config Split is an environment; with environment_context_environment_indicator, each Environment Indicator environment. Each server names its environment by machine name in settings.php, or in the DRUPAL_ENVIRONMENT environment variable:

$settings['environment'] = 'production';

Sub-sites inherit

A sub-site with Inherit settings from the main site checked on its Identity section takes its main site's value for every setting it leaves empty. A setting with a default from the type or the module is not empty, so it keeps that default.

settings.php

A value in settings.php wins over every other layer. The key is the site's ID, the entries are setting keys from the settings reference:

// Sites Analytics: the Matomo site of Acme on this server.
$settings['acme'] = [
  'matomo_site_id' => '12',
  'matomo_url' => 'https://matomo.example.com/',
];

The value stays out of the database and the configuration export. The admin UI keeps showing the saved value; drush sites:info acme lists the settings.php value under settings.

Keep hostnames out of settings.php: a hostname there changes the site's links, while requests reach the site on neither the old nor the new hostname. Set hostnames per environment on the Identity section; see Hostnames.

Configuration overrides per site

A setting marked "Config" in the reference changes Drupal configuration on one site only. A site's Site name replaces the platform's site name on the site's hostname, its Theme the default theme; the hub keeps the platform's configuration. These per-site values belong to the site, like its content: they are not part of the configuration export. drush sites:info acme lists them under overrides.