Version: v1

Settings

Drupal reads its site configuration from settings.php and services.yml: database connections, file paths, and everything that should behave differently from one environment to the next. Vortex ships its own versions of settings.php and services.yml, built so the same files work in every environment.

The shipped settings.php works out where the site is running (locally, in CI, or in a hosting environment) and applies settings to match. Each module's overrides live in a small file of their own, so you can see at a glance what a module does differently in each environment.

Drupal Scaffold's own default.settings.php and default.services.yml are there too, if you'd rather start from those.

This page is for developers who need a setting to differ between environments, and for the lead or DevOps engineer bringing a project onto a hosting platform. It explains how settings.php detects the environment and which variables it reads. It also shows how to add your own per-module overrides and test them. For the full list of variables, see Variables.

Approach

A site rarely runs the same way everywhere. Local, CI, development, staging, and production environments each need their own adjustments: a module on here and off there, different performance settings, different APIs, or different services to talk to.

Drupal has no standard way to manage these differences. Its configuration system isn't built for conditional logic, such as applying different settings per runtime environment or reading values from environment variables.

Modules like config_split let you maintain separate configuration sets per environment, but they're limited. They don't support environment-based conditions inside the configuration YAML files, and they can't read environment variables directly. They also don't help when you need dynamic logic (for example, setting values based on external service URLs).

Vortex still ships config_split, and it's the right tool when declarative configuration is enough, such as enabling a module in staging but not in production. It falls short when settings need conditional logic or values from the environment. It also gives you no way to test automatically which settings apply in a given environment.

So Vortex splits the job in 2:

The environment type is detected from the environment the site runs in. This step applies the hosting platform's own settings, but no module configuration.
Configuration overrides live in per-module override files, with conditions based on the detected environment type.

The split pays off in 4 ways:

It keeps environment detection separate from configuration logic.
It shows in one place how a module behaves in a specific environment.
It lets you delete a module's override file without touching settings.php when the module is no longer needed.
It stops environment-specific settings from leaking into unrelated parts of the configuration.

In practice

Say the business asks to let an external stakeholder review the stage environment, which Shield protects with HTTP authentication. The shipped settings.shield.php override already reads the DRUPAL_SHIELD_DISABLED variable, so you can make the change without editing code:

In your hosting provider's environment variables, set DRUPAL_SHIELD_DISABLED=1 on the stage environment.
Apply the variable: Acquia restarts the environment on its own, and Lagoon needs a redeployment. The stage site then opens without the HTTP authentication prompt.

When the review is over, remove the variable and apply the change the same way. Confirm that the stage site asks for the Shield credentials again.

You don't commit anything, and no other environment changes, because the override file defines the behavior once and each environment opts in through its own variables.

Settings file structure

The settings.php file is organized into the following sections:

Database
General
Environment type detection
Per-module overrides
Local overrides

The sections run in a fixed order, loading additional files from the includes/ directories along the way:

🚀 Drupal bootstrap
   │
   ▼
📄 web/sites/default/settings.php
   │
① 🛢️ Database
   │  Connection credentials from environment variables.
   ▼
② ⚙️ General
   │  File paths, hash salt, timezone, maintenance theme.
   ▼
③ 🔍 Environment type detection
   │  Loads web/sites/default/includes/providers/settings.<provider>.php
   │  (acquia, lagoon, circleci, gha, container) and stores the detected
   │  type in $settings['environment']. Provider files also apply their
   │  platform settings; no module overrides are applied here.
   ▼
④ 🧩 Per-module overrides
   │  Loads every web/sites/default/includes/modules/settings.<module>.php,
   │  each applying its overrides based on the detected environment type.
   ▼
⑤ 🏠 Local overrides
   │  Loads web/sites/default/settings.local.php and services.local.yml
   │  when present (local development only).
   ▼
🏁 Fully configured site

Projects with the migration feature load 1 more file between the per-module overrides and the local overrides: settings.migration.php, which defines the migration database connection.

Expand to see settings.php

<?php

/**
 * @file
 * Drupal site-specific configuration file.
 *
 * Copy `example.settings.local.php` and `example.services.local.yml` to
 * `settings.local.php` and `services.local.yml` respectively to
 * enable local overrides.
 *
 * It’s recommended to leave this file unchanged and manage configuration
 * through environment variables and module-specific settings files instead.
 * This allows for better portability and easier management of settings across
 * environments.
 * @see https://www.vortextemplate.com/docs/development/settings
 *
 * phpcs:disable Drupal.Commenting.InlineComment.NoSpaceBefore
 * phpcs:disable Drupal.Commenting.InlineComment.SpacingAfter
 * phpcs:disable DrupalPractice.Commenting.CommentEmptyLine.SpacingAfter
 * phpcs:disable DrupalPractice.CodeAnalysis.VariableAnalysis.UnusedVariable
 */

declare(strict_types=1);

////////////////////////////////////////////////////////////////////////////////
///                               DATABASE                                   ///
////////////////////////////////////////////////////////////////////////////////
// @see https://www.vortextemplate.com/docs/development/settings#database

$databases = [
  'default' =>
    [
      'default' =>
        [
          'database' => (getenv('DATABASE_NAME') ?: getenv('DATABASE_DATABASE') ?: getenv('MARIADB_DATABASE')) ?: 'drupal',
          'username' => (getenv('DATABASE_USERNAME') ?: getenv('MARIADB_USERNAME')) ?: 'drupal',
          'password' => (getenv('DATABASE_PASSWORD') ?: getenv('MARIADB_PASSWORD')) ?: 'drupal',
          'host' => (getenv('DATABASE_HOST') ?: getenv('MARIADB_HOST')) ?: 'localhost',
          'port' => (getenv('DATABASE_PORT') ?: getenv('MARIADB_PORT')) ?: '3306',
          'charset' => (getenv('DATABASE_CHARSET') ?: getenv('MARIADB_CHARSET') ?: getenv('MYSQL_CHARSET')) ?: 'utf8mb4',
          'collation' => (getenv('DATABASE_COLLATION') ?: getenv('MARIADB_COLLATION') ?: getenv('MYSQL_COLLATION')) ?: 'utf8mb4_general_ci',
          'prefix' => '',
          'driver' => 'mysql',
        ],
    ],
];

////////////////////////////////////////////////////////////////////////////////
///                               GENERAL                                    ///
////////////////////////////////////////////////////////////////////////////////
// @see https://www.vortextemplate.com/docs/development/settings#general

$app_root ??= DRUPAL_ROOT;
$site_path ??= 'sites/default';
// phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
$contrib_path = $app_root . '/' . (is_dir($app_root . '/modules/contrib') ? 'modules/contrib' : 'modules');

// Public files directory relative to the Drupal root.
$settings['file_public_path'] = getenv('DRUPAL_PUBLIC_FILES') ?: 'sites/default/files';

// Private files directory relative to the Drupal root.
$settings['file_private_path'] = getenv('DRUPAL_PRIVATE_FILES') ?: 'sites/default/files/private';

// Temporary file directory.
$settings['file_temp_path'] = (getenv('DRUPAL_TEMPORARY_FILES') ?: getenv('TMP')) ?: '/tmp';

// Location of the site configuration files relative to the Drupal root.
$settings['config_sync_directory'] = getenv('DRUPAL_CONFIG_PATH') ?: '../config/default';

// Load services definition file.
$settings['container_yamls'][] = $app_root . '/' . $site_path . '/services.yml';

// Use DRUPAL_HASH_SALT or the database host name for salt.
$settings['hash_salt'] = getenv('DRUPAL_HASH_SALT') ?: hash('sha256', $databases['default']['default']['host']);

// Timezone settings.
ini_set('date.timezone', (getenv('DRUPAL_TIMEZONE') ?: getenv('TZ')) ?: 'UTC');
date_default_timezone_set((getenv('DRUPAL_TIMEZONE') ?: getenv('TZ')) ?: 'UTC');

// Maintenance theme.
$settings['maintenance_theme'] = (getenv('DRUPAL_MAINTENANCE_THEME') ?: getenv('DRUPAL_THEME')) ?: 'claro';

// Trusted Host Patterns.
// See https://www.drupal.org/node/2410395 for more information on how to
// populate this array.
// Settings for specific environments (including a local container-based
// environment) are populated within provider-specific
// `includes/providers/settings.<provider>.php` files.
// @see https://www.vortextemplate.com/docs/development/settings#environment-type-detection
$settings['trusted_host_patterns'] = [
  '^localhost$',
];

// Modules excluded from config export.
// Populate this array in the `includes/modules/settings.<module>.php` file.
$settings['config_exclude_modules'] = [];

// The default list of directories that will be ignored by Drupal's file API.
$settings['file_scan_ignore_directories'] = [
  'node_modules',
  'bower_components',
];

// Do not automatically create an Apache HTTP .htaccess file in writable
// directories. Overridden in hosting provider settings files as needed.
$settings['auto_create_htaccess'] = FALSE;

// The default number of entities to update in a batch process.
$settings['entity_update_batch_size'] = 50;

////////////////////////////////////////////////////////////////////////////////
///                       ENVIRONMENT TYPE DETECTION                         ///
////////////////////////////////////////////////////////////////////////////////
// @see https://www.vortextemplate.com/docs/development/settings#environment-type-detection

// Use these constants anywhere in code to alter behavior for a specific
// environment.
// @codeCoverageIgnoreStart
if (!defined('ENVIRONMENT_LOCAL')) {
  define('ENVIRONMENT_LOCAL', 'local');
}
if (!defined('ENVIRONMENT_CI')) {
  define('ENVIRONMENT_CI', 'ci');
}
if (!defined('ENVIRONMENT_DEV')) {
  define('ENVIRONMENT_DEV', 'dev');
}
if (!defined('ENVIRONMENT_STAGE')) {
  define('ENVIRONMENT_STAGE', 'stage');
}
if (!defined('ENVIRONMENT_PROD')) {
  define('ENVIRONMENT_PROD', 'prod');
}
// @codeCoverageIgnoreEnd

// Default environment type is 'local'.
$settings['environment'] = ENVIRONMENT_LOCAL;

// Load provider-specific environment detection settings.
if (file_exists($app_root . '/' . $site_path . '/includes/providers')) {
  $files = glob($app_root . '/' . $site_path . '/includes/providers/settings.*.php');
  if ($files) {
    foreach ($files as $file) {
      require $file;
    }
  }
}

// Allow overriding the environment type using the ENVIRONMENT_TYPE variable.
$environment_type = getenv('ENVIRONMENT_TYPE');
if (!empty($environment_type)) {
  $settings['environment'] = $environment_type;
}

////////////////////////////////////////////////////////////////////////////////
///                       PER-MODULE OVERRIDES                               ///
////////////////////////////////////////////////////////////////////////////////
// @see https://www.vortextemplate.com/docs/development/settings#per-module-overrides

if (file_exists($app_root . '/' . $site_path . '/includes/modules')) {
  $files = glob($app_root . '/' . $site_path . '/includes/modules/settings.*.php');
  if ($files) {
    foreach ($files as $file) {
      require $file;
    }
  }
}

// phpcs:ignore #;< MIGRATION
////////////////////////////////////////////////////////////////////////////////
///                          MIGRATION SETTINGS                              ///
////////////////////////////////////////////////////////////////////////////////
// @todo Migration. Remove when migration configuration is no longer required.
if (file_exists($app_root . '/' . $site_path . '/settings.migration.php')) {
  require $app_root . '/' . $site_path . '/settings.migration.php';
}
// phpcs:ignore #;> MIGRATION

////////////////////////////////////////////////////////////////////////////////
///                          LOCAL OVERRIDE                                  ///
////////////////////////////////////////////////////////////////////////////////
// @see https://www.vortextemplate.com/docs/development/settings#local-overrides

// Load local override configuration, if available.
//
// Copy `example.settings.local.php` and `example.services.local.yml` to
// `settings.local.php` and `services.local.yml` respectively to enable local
// overrides.
//
// `services.local.yml` is loaded from within `settings.local.php`.
//
// Keep this code block at the end of this file to take full effect.
// @codeCoverageIgnoreStart
if (file_exists($app_root . '/' . $site_path . '/settings.local.php') && getenv('DRUPAL_SETTINGS_LOCAL_SKIP') !== '1') {
  require $app_root . '/' . $site_path . '/settings.local.php';
}
// @codeCoverageIgnoreEnd

Database

The database connection comes from environment variables, with a default for each value.

Hosting providers and container images name these variables differently, so each setting accepts several names and uses the first one that's set:

Variable	Alternative variables	Default	Purpose
`DATABASE_NAME`	`DATABASE_DATABASE`, `MARIADB_DATABASE`	`drupal`	Database name
`DATABASE_USERNAME`	`MARIADB_USERNAME`	`drupal`	Database username
`DATABASE_PASSWORD`	`MARIADB_PASSWORD`	`drupal`	Database password
`DATABASE_HOST`	`MARIADB_HOST`	`localhost`	Database host
`DATABASE_PORT`	`MARIADB_PORT`	`3306`	Database port
`DATABASE_CHARSET`	`MARIADB_CHARSET`, `MYSQL_CHARSET`	`utf8mb4`	Character set
`DATABASE_COLLATION`	`MARIADB_COLLATION`, `MYSQL_COLLATION`	`utf8mb4_general_ci`	Collation

The table prefix is always empty, and the driver is always mysql.

You rarely need to set these yourself: the local stack sets them in docker-compose.yml, and the alternative names cover providers and images that use their own. For a custom database setup, or a hosting provider that needs specific values, set them in that environment.

General

This section sets the values every environment needs, and it doesn't look at the environment type. The provider files in the next section adjust a few of these values for their platform, such as the temporary directory on Acquia.

The following environment variables customize it:

Variable	Alternative variables	Default	Purpose
`DRUPAL_CONFIG_PATH`	None	`../config/default`	Location of configuration sync directory
`DRUPAL_PUBLIC_FILES`	None	`sites/default/files`	Public files directory path
`DRUPAL_PRIVATE_FILES`	None	`sites/default/files/private`	Private files directory path
`DRUPAL_TEMPORARY_FILES`	`TMP`	`/tmp`	Temporary files directory path
`DRUPAL_HASH_SALT`	None	SHA-256 hash of the database host	Cryptographic salt for security
`DRUPAL_TIMEZONE`	`TZ`	`UTC`	Runtime timezone
`DRUPAL_MAINTENANCE_THEME`	`DRUPAL_THEME`	`claro`	Theme used during maintenance mode

It also does the following, and no variable changes it:

Loads services.yml as a service container definition
Trusts the ^localhost$ host pattern
Skips the node_modules and bower_components directories in file scans
Sets auto_create_htaccess to FALSE, so Drupal creates no .htaccess files in writable directories; settings.acquia.php turns it back on for Acquia
Updates entities in batches of 50
Starts an empty config_exclude_modules list for the per-module files to fill

The page cache lifetime (DRUPAL_CACHE_PAGE_MAX_AGE, default 900 seconds) is set in the settings.system.php per-module override, not in this section. The full generated list of DRUPAL_* variables is in the Variables reference.

Hash salt

The DRUPAL_HASH_SALT variable sets Drupal's hash_salt, which secures one-time login links, password-reset URLs, and CSRF/form tokens.

When DRUPAL_HASH_SALT isn't set, Vortex derives a fallback salt by hashing the database host name. That gets a new project running without any setup, and it's fine for local and CI use, but nowhere else:

A database host isn't a secret. It appears in logs, backups, .env files, and drush status output, so the derived value only resists blind guessing.
The derived value changes if the database host ever changes (for example, failover or migration), silently invalidating outstanding one-time login and password-reset links.

warning

Set a unique, long, random DRUPAL_HASH_SALT for every hosted environment, meaning dev, stage, and production, as a platform variable or secret. settings.lagoon.php sets no salt of its own. On Acquia, settings.acquia.php loads the platform's settings file after this section, so a salt set in that file takes precedence. See Set up hosting for each platform's steps.

Environment type detection

The environment type names the context the Drupal site runs in, such as local, CI, development, staging, or production. Settings and scripts check it to decide how to behave in each one.

Vortex detects the type automatically from variables that known hosting provider and CI platforms set. The provider files that do the detecting also apply their platform's own settings, but they leave module configuration to the per-module override files.

The detected type lands in $settings['environment'], where modules, settings overrides, and shell scripts read it to drive environment-specific behavior.

Environment type constants

Vortex defines a constant for each supported environment type, with the string value it stands for:

ENVIRONMENT_LOCAL (local)
ENVIRONMENT_CI (ci)
ENVIRONMENT_DEV (dev)
ENVIRONMENT_STAGE (stage)
ENVIRONMENT_PROD (prod)

Settings files compare $settings['environment'] against these constants, and shell scripts compare it against the string values.

Detection mechanism

Detection relies on variables that hosting and CI platforms set. The logic lives in the includes/providers directory, 1 file per provider, and each file acts only when the variable its platform sets is present:

settings.acquia.php: AH_SITE_ENVIRONMENT
settings.circleci.php and settings.gha.php: CI
settings.container.php: LOCALDEV_URL
settings.lagoon.php: LAGOON_KUBERNETES

settings.php loads every settings.*.php file in that directory, in alphabetical order.

To add support for a custom platform, create a settings.[provider].php file in that directory with the relevant detection logic.

The type starts as ENVIRONMENT_LOCAL, and the provider files change it:

A hosting provider sets ENVIRONMENT_DEV, and its own conditions raise that to ENVIRONMENT_STAGE or ENVIRONMENT_PROD:
- On Acquia, an AH_SITE_ENVIRONMENT of prod becomes ENVIRONMENT_PROD, and stage or test becomes ENVIRONMENT_STAGE.
- On Lagoon, a LAGOON_ENVIRONMENT_TYPE of production becomes ENVIRONMENT_PROD. So does a LAGOON_GIT_BRANCH that exactly matches VORTEX_LAGOON_PRODUCTION_BRANCH, which .env sets to main; when that variable is empty, the branch check is skipped. Otherwise, the main and master branches and any branch starting with release/ or hotfix/ become ENVIRONMENT_STAGE.
settings.circleci.php and settings.gha.php both check the generic CI variable, not a provider-specific one such as CIRCLECI. Any non-empty value other than 0 sets ENVIRONMENT_CI, and docker-compose.yml passes CI from the runner into the containers.
settings.container.php sets no type. It adds the local container URLs from LOCALDEV_URL to the trusted host patterns.
With no provider detected, the type stays ENVIRONMENT_LOCAL.

Besides the type, the provider files apply only their platform's own settings. Examples are Acquia's settings include and temporary directory, the reverse proxy and cache prefix on Lagoon, and trusted host patterns. They don't change module configuration. Per-module override files in includes/modules handle that separately, so the setup stays modular and independent of the hosting platforms.

Overriding environment type

To force a specific environment type, set the ENVIRONMENT_TYPE environment variable. Any non-empty value replaces the detected type, including names outside the 5 constants.

Overriding the type helps in the following cases:

Testing environment-specific behavior locally
Working around gaps in the detection logic
Forcing a known environment type for debugging

For example, to simulate the CI environment locally, add ENVIRONMENT_TYPE=ci to your .env.local file and run ahoy up.

Per-module overrides

This section loads every settings.[module].php file from the includes/modules directory, in alphabetical order. Each file holds the configuration overrides for 1 Drupal module, or for 1 concern such as trusted hosts.

Vortex ships an override file for each contributed module it configures, so you can maintain or remove each one independently. It also ships 3 files that don't belong to a contributed module:

settings.automated_cron.php sets the Automated Cron interval to 0 in the local and ci environments, so cron doesn't run on page requests there.
settings.system.php sets the page cache lifetime and turns on CSS and JavaScript aggregation in prod. In local and ci, it shows all errors and skips file permissions hardening. In ci, it stores outgoing email in the state system instead of sending it.
settings.trusted_hosts.php adds each domain in the comma-separated DRUPAL_TRUSTED_HOSTS variable to the trusted host patterns.

➡️ See Contributed modules for what each shipped override configures, module by module.

Creating custom module settings

To add settings for a new module, create a file following the naming pattern:

web/sites/default/includes/modules/settings.[module_name].php

Each settings file follows these rules:

Use environment type constants (such as ENVIRONMENT_LOCAL and ENVIRONMENT_PROD) for conditional logic
Use environment variables for configuration values
Provide default values for when environment variables aren't set
Be self-contained and removable without affecting other modules

The following override file for the Environment Indicator module follows these rules:

Example settings.environment_indicator.php

<?php

/**
 * @file
 * Environment indicator settings.
 */

declare(strict_types=1);

$config['environment_indicator.indicator']['name'] = $settings['environment'];
$config['environment_indicator.indicator']['bg_color'] = '#006600';
$config['environment_indicator.indicator']['fg_color'] = '#ffffff';
$config['environment_indicator.settings']['toolbar_integration'] = [TRUE];
$config['environment_indicator.settings']['favicon'] = TRUE;

switch ($settings['environment']) {
  case ENVIRONMENT_PROD:
    $config['environment_indicator.indicator']['bg_color'] = '#ef5350';
    $config['environment_indicator.indicator']['fg_color'] = '#000000';
    break;

  case ENVIRONMENT_STAGE:
    $config['environment_indicator.indicator']['bg_color'] = '#fff176';
    $config['environment_indicator.indicator']['fg_color'] = '#000000';
    break;

  case ENVIRONMENT_DEV:
    $config['environment_indicator.indicator']['bg_color'] = '#4caf50';
    $config['environment_indicator.indicator']['fg_color'] = '#000000';
    break;
}

Local overrides

settings.php ends by loading settings.local.php when it exists, so you can override settings on your machine without touching the shared configuration. To turn the local overrides on, follow these steps in web/sites/default:

Copy example.settings.local.php to settings.local.php.
Copy example.services.local.yml to services.local.yml.

Git ignores both copies, and settings.local.php is the file that loads services.local.yml. Drupal builds a new service container when that list of service files changes, so no cache rebuild is needed. Confirm that the HTML source of the next page you load carries Twig debug comments, such as .

The example files change the following settings:

Every error message shows, with backtrace information.
CSS and JavaScript aggregation is off.
The render, page, and dynamic page caches are bypassed.
Twig debugging is on.
Responses carry cacheability debug headers.
rebuild.php is accessible.
File permissions hardening is skipped.

To check how the site behaves without the local overrides, set the DRUPAL_SETTINGS_LOCAL_SKIP environment variable to 1. The site then skips settings.local.php even when it exists.

Expand to see example.settings.local.php

<?php

/**
 * @file
 * Local development override configuration feature.
 *
 * To activate this feature, copy and rename it such that its path plus
 * filename is 'sites/default/settings.local.php'. No changes to settings.php
 * are required as it automatically loads settings.local.php if present.
 *
 * If you are using a site name in the path, such as 'sites/example.com', copy
 * this file to 'sites/example.com/settings.local.php'.
 *
 * @see https://git.drupalcode.org/project/drupal/-/blob/11.x/core/assets/scaffold/files/example.settings.local.php
 */

declare(strict_types=1);

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

/**
 * Show all error messages, with backtrace information.
 *
 * In case the error level could not be fetched from the database, as for
 * example the database connection failed, we rely only on this value.
 */
$config['system.logging']['error_level'] = 'verbose';

/**
 * Disable CSS and JS aggregation.
 */
$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;

/**
 * Disable the render cache.
 *
 * Note: you should test with the render cache enabled, to ensure the correct
 * cacheability metadata is present. However, in the early stages of
 * development, you may want to disable it.
 *
 * This setting disables the render cache by using the Null cache back-end
 * defined by the development.services.yml file above.
 *
 * Only use this setting once the site has been installed.
 */
$settings['cache']['bins']['render'] = 'cache.backend.null';

/**
 * Disable caching for migrations.
 *
 * Uncomment the code below to only store migrations in memory and not in the
 * database. This makes it easier to develop custom migrations.
 */
# $settings['cache']['bins']['discovery_migration'] = 'cache.backend.memory';

/**
 * Disable Internal Page Cache.
 *
 * Note: you should test with Internal Page Cache enabled, to ensure the correct
 * cacheability metadata is present. However, in the early stages of
 * development, you may want to disable it.
 *
 * This setting disables the page cache by using the Null cache back-end
 * defined by the development.services.yml file above.
 *
 * Only use this setting once the site has been installed.
 */
$settings['cache']['bins']['page'] = 'cache.backend.null';

/**
 * Disable Dynamic Page Cache.
 *
 * Note: you should test with Dynamic Page Cache enabled, to ensure the correct
 * cacheability metadata is present (and hence the expected behavior). However,
 * in the early stages of development, you may want to disable it.
 */
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

/**
 * Allow test modules and themes to be installed.
 *
 * Drupal ignores test modules and themes by default for performance reasons.
 * During development it can be useful to install test extensions for debugging
 * purposes.
 */
# $settings['extension_discovery_scan_tests'] = TRUE;

/**
 * Enable access to rebuild.php.
 *
 * This setting can be enabled to allow Drupal's php and database cached
 * storage to be cleared via the rebuild.php page. Access to this page can also
 * be gained by generating a query string from rebuild_token_calculator.sh and
 * using these parameters in a request to rebuild.php.
 */
$settings['rebuild_access'] = TRUE;

/**
 * Skip file system permissions hardening.
 *
 * The system module will periodically check the permissions of your site's
 * site directory to ensure that it is not writable by the website user. For
 * sites that are managed with a version control system, this can cause problems
 * when files in that directory such as settings.php are updated, because the
 * user pulling in the changes won't have permissions to modify files in the
 * directory.
 */
$settings['skip_permissions_hardening'] = TRUE;

/**
 * Hide administration navigation. Useful for theming while logged in as admin.
 */
// $settings['hide_admin_navigation'] = TRUE;

Expand to see example.services.local.yml

# Local development services.
#
# The example.services.local.yml file allows the developer to override
# container parameters for debugging.
#
# To activate this feature, follow the instructions at the top of the
# 'example.settings.local.php' file, which sits next to this file.
#
# Be aware that in Drupal's configuration system, all the files that
# provide container definitions are merged using a shallow merge approach
# within \Drupal\Core\DependencyInjection\YamlFileLoader.
# This means that if you want to override any value of a parameter, the
# whole parameter array needs to be copied from
# sites/default/default.services.yml or from core/core.services.yml file.
#
# @see https://git.drupalcode.org/project/drupal/-/blob/11.x/core/assets/scaffold/files/development.services.yml
parameters:
  http.response.debug_cacheability_headers: true
  # Enable Twig debugging and caching (auto_reload inherits core default).
  twig.config:
    debug: true
    auto_reload: null
    # Twig cache allows Xdebug to work with .twig files.
    cache: true
services:
  cache.backend.null:
    class: Drupal\Core\Cache\NullBackendFactory
  logger.channel.config_schema:
    parent: logger.channel_base
    arguments: [ 'config_schema' ]
  config.schema_checker:
    class: Drupal\Core\Config\Development\LenientConfigSchemaChecker
    arguments:
      - '@config.typed'
      - '@messenger'
      - '@logger.channel.config_schema'
    tags:
      - { name: event_subscriber }

Guidelines

Follow these guidelines when working with settings:

Don't modify settings.php directly.
Use environment variables for general settings or per-module override files for any custom or environment-aware configuration.
Keep all overrides isolated by module.
Each file holds the logic for a single module only. When the module goes, its override file goes with it, and no unrelated setting changes.
Use environment variables for configuration that changes by environment.
Prefix all such variables with DRUPAL_ (for example, DRUPAL_MY_SETTING) to distinguish them from other environment variables.
Always define a default hardcoded value for each environment variable.
Guard a variable by what it holds.
A boolean flag (a variable whose only job is to switch behavior on) is read with getenv('DRUPAL_MY_FLAG') === '1'. Every other value, including an unset variable, an empty string, 0, true, and yes, leaves the behavior off.
A value carrier (a variable whose value is used) is read with !empty(getenv('DRUPAL_MY_VALUE')). Assign it to a variable first when the value is needed after the guard.
Compare with === and !==, never with ==.

Flags accept only 1

Each of the following flags acts only when it's exactly 1. Any other value, such as true, yes, or on, counts as unset, so the flag has no effect. Set each one to exactly 1, wherever you set it:

DRUPAL_CLAMAV_ENABLED
DRUPAL_REDIS_ENABLED
DRUPAL_REROUTE_EMAIL_DISABLED
DRUPAL_SHIELD_DISABLED
DRUPAL_SHIELD_ALLOW_ACME_CHALLENGE
DRUPAL_TMP_PATH_IS_SHARED
DRUPAL_SETTINGS_LOCAL_SKIP
VORTEX_REDIS_EXTENSION_LOADED

Gate on the presence of a contributed module only when the file needs it.
file_exists($contrib_path . '/my_module') belongs in an override file that loads a file from the module directory or registers its paths. An override file that only writes $config or $settings needs no such guard, because Drupal ignores overrides for a module that isn't installed.
Use conditions based on environment type within per-module override files.
This keeps environment-specific configuration out of the main settings.php file.
Use the $settings['environment'] variable to check the current environment type.

Testing settings with unit tests

Vortex includes a set of unit tests to verify that settings are applied correctly for each detected environment type.

They're meant to be maintained in your project, alongside your settings. They check that environment-driven configuration behaves as expected, for each environment type and for the environment variables that switch behavior on or off. The 3 test classes cover the following:

DatabaseSettingsTest: the database connection settings
EnvironmentSettingsTest: the settings in every environment type
SwitchableSettingsTest: the settings that environment variables switch on or off

To run only the settings tests, run the following command inside the CLI container (open a shell there with ahoy cli):

vendor/bin/phpunit --group=drupal_settings

Confirm that PHPUnit reports OK at the end of the run.

They're part of the unit test suite, so ahoy test-unit runs them too. Remove these tests if you don't want to maintain them.

Approach​

In practice​

Settings file structure​

Database​

General​

Hash salt​

Environment type detection​

Environment type constants​

Detection mechanism​

Overriding environment type​

Per-module overrides​

Creating custom module settings​

Local overrides​

Guidelines​

Testing settings with unit tests​