Settings

The settings.php file provides the primary configuration for a Drupal site, including its database connection, file paths, and various other settings.

Vortex ships with own streamlined version of the settings.php and services.yml files.

It also provides Settings unit tests to ensure that the settings apply correctly per environment. These tests are intended to be maintained within your project, ensuring that the settings activated within a specific environment type and with specific environment variables are applied correctly.

The default Drupal Scaffold's default.settings.php and default.services.yml files are also provided if you choose to use them instead.

The settings.php file is divided into several sections:

Click here to see the contents of the settings.php file

<?php

/**
 * @file
 * Drupal site-specific configuration file.
 *
 * The structure of this file:
 * - Environment type constants definitions.
 * - Site-specific settings.
 * - Inclusion of hosting providers settings.
 * - Per-environment overrides.
 * - Inclusion of local settings.
 *
 * Create settings.local.php file to include local settings overrides.
 *
 * 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);

////////////////////////////////////////////////////////////////////////////////
///                       ENVIRONMENT TYPE CONSTANTS                         ///
////////////////////////////////////////////////////////////////////////////////

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

$settings['environment'] = empty(getenv('CI')) ? ENVIRONMENT_LOCAL : ENVIRONMENT_CI;

////////////////////////////////////////////////////////////////////////////////
///                       SITE-SPECIFIC SETTINGS                             ///
////////////////////////////////////////////////////////////////////////////////

$app_root = $app_root ?? DRUPAL_ROOT;
$site_path = $site_path ?? 'sites/default';
$contrib_path = $app_root . DIRECTORY_SEPARATOR . (is_dir($app_root . DIRECTORY_SEPARATOR . 'modules/contrib') ? 'modules/contrib' : 'modules');

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

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

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

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

// Base salt on the DB host name.
$settings['hash_salt'] = hash('sha256', getenv('DATABASE_HOST') ?: 'localhost');

// Expiration of cached pages.
$config['system.performance']['cache']['page']['max_age'] = 900;

// Aggregate CSS and JS files.
$config['system.performance']['css']['preprocess'] = TRUE;
$config['system.performance']['js']['preprocess'] = TRUE;

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

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

// Trusted Host Patterns.
// Settings for other environments are included below.
// If your site runs on multiple domains, you need to add these domains here.
// escape dots, remove schema, use commas as regex separator.
// See https://www.drupal.org/node/2410395 for more information.
$settings['trusted_host_patterns'] = [
  // Local URL.
  '^.+\.docker\.amazee\.io$',
  // URL when accessed from Behat tests.
  '^nginx$',
];

// Modules excluded from config export.
$settings['config_exclude_modules'] = [];

ini_set('date.timezone', 'Australia/Melbourne');
date_default_timezone_set('Australia/Melbourne');

// Maintenance theme.
$config['maintenance_theme'] = 'your_site_theme';

// Default database configuration.
$databases = [
  'default' =>
    [
      'default' =>
        [
          'database' => getenv('DATABASE_NAME') ?: 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') ?: '',
          'prefix' => '',
          'driver' => 'mysql',
        ],
    ],
];

////////////////////////////////////////////////////////////////////////////////
///                       ENVIRONMENT TYPE DETECTION                         ///
////////////////////////////////////////////////////////////////////////////////

// Load provider-specific 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 $filename) {
      require $filename;
    }
  }
}

// Allow overriding of an environment type.
if (!empty(getenv('DRUPAL_ENVIRONMENT'))) {
  $settings['environment'] = getenv('DRUPAL_ENVIRONMENT');
}

////////////////////////////////////////////////////////////////////////////////
///                   ENVIRONMENT-SPECIFIC SETTINGS                          ///
////////////////////////////////////////////////////////////////////////////////

if ($settings['environment'] == ENVIRONMENT_CI) {
  // Never harden permissions on sites/default/files.
  $settings['skip_permissions_hardening'] = TRUE;

  // Disable built-in cron trigger.
  $config['automated_cron.settings']['interval'] = 0;

  // Disable mail send out.
  $settings['suspend_mail_send'] = TRUE;
}

if ($settings['environment'] == ENVIRONMENT_LOCAL) {
  // Never harden permissions on sites/default/files during local development.
  $settings['skip_permissions_hardening'] = TRUE;

  // Disable built-in cron trigger.
  $config['automated_cron.settings']['interval'] = 0;

  // Show all error messages on the site.
  $config['system.logging']['error_level'] = 'all';
}

////////////////////////////////////////////////////////////////////////////////
///                       PER-MODULE SETTINGS                                ///
////////////////////////////////////////////////////////////////////////////////

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

////////////////////////////////////////////////////////////////////////////////
///                          LOCAL SETTINGS                                  ///
////////////////////////////////////////////////////////////////////////////////

// Load local development override configuration, if available.
//
// Copy default.settings.local.php and default.services.local.yml to
// settings.local.php and services.local.yml respectively.
// services.local.yml is loaded in in 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')) {
  require $app_root . '/' . $site_path . '/settings.local.php';
}
// @codeCoverageIgnoreEnd

Environment type constants definitions
Site-specific settings
Environment detection
Per-environment overrides
Inclusion of generated Settings
Inclusion of local settings

1. Environment type constants definitions

Constants for various environment types are defined here. These can be used to alter site behavior based on the active environment type.

Available environment type constants are:

ENVIRONMENT_LOCAL
ENVIRONMENT_CI
ENVIRONMENT_PROD
ENVIRONMENT_STAGE
ENVIRONMENT_DEV

These are later used to set $settings['environment'], which can be used in the modules and shell scripts to target code execution to specific environments types.

EXAMPLE

environment="$(drush php:eval "print \Drupal\core\Site\Settings::get('environment');")"
if echo "${environment}" | grep -q -e ci -e local; then
  # Do something only in ci or local environments.
fi

info

The $VORTEX_PROVISION_ENVIRONMENT environment variable can be utilized within post-provision custom scripts instead of Drush command evaluation, allowing targeted code execution based on a specific environment type. Refer to Provision for additional information.

2. Site-specific settings

This section is used for configuring core site settings such as defining paths, ensuring security with trusted host patterns, setting performance optimizations like aggregating CSS and JS files, and specifying essential directories for Drupal's functionality.

These settings are identical for all environment types .

Use per-module settings files in the web/site/default/includes/modules directory to override per-module settings.

3. Environment type detection

This section uses known hosting providers mechanisms to determine the environment type where the site currently runs.

Settings for the supported hosting providers are stored in the web/site/default/includes/providers directory. You can add your own custom provider environment type detection logic by creating a new file settings.[provider].php in this directory.

Once a hosting provider is detected, the environment type $settings['environment'] is set to ENVIRONMENT_DEV for all environments as a default.

Higher-level environments types (PROD, STAGE etc.) are then set based on the additional detected provider-specific settings.

When the hosting provider is not detected, the default value is set to ENVIRONMENT_LOCAL.

note

Environment type detection settings are only used for environment type detection and not for environment-specific settings. Those are defined in the Per-environment overrides section. This approach allows for a more flexible and maintainable configuration independent of a specific hosting provider.

Overriding environment type

It is also possible to force specific environment type by setting DRUPAL_ENVIRONMENT environment variable.

This is useful in cases where a certain behavior is required for a specific environment, but the environment type detection logic does not provide it.

It is also useful when debugging environment type-specific issues locally.

4. Per-environment overrides

Configurations in this section alter the site's behavior based on the detected environment type (see Environment type detection above). Out-of-the-box, Vortex provides overrides for CI and Local environments.

You can add additional overrides for other environment types as needed.

5. Inclusion of per-module settings

This section includes any additional module-specific settings from the web/site/default/includes/modules directory.

Vortex ships with settings overrides for several popular contributed modules.

The per environment type overrides for each module should be placed into the module-specific settings file.

Example of the Environment indicator module settings file

<?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;
}

6. Inclusion of local settings

At the end of the settings.php, there is an option to include additional local settings. This allows developers to override some settings for their local environment without affecting the main configuration. Developers can copy default.settings.local.php and default.services.local.yml to settings.local.php and services.local.yml, respectively, to utilize this functionality.

Click here to see the contents of the default.settings.local.php file

<?php

/**
 * @file
 * Settings file for local environment.
 */

declare(strict_types=1);

if (file_exists($app_root . '/' . $site_path . '/services.local.yml')) {
  $settings['container_yamls'][] = $app_root . '/' . $site_path . '/services.local.yml';
}

// Show all error messages on the site.
$config['system.logging']['error_level'] = 'all';

// Disable caching.
$config['system.performance']['cache']['page']['max_age'] = 0;
$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';
$settings['cache']['bins']['page'] = 'cache.backend.null';
$settings['extension_discovery_scan_tests'] = FALSE;

// Disable CSS files aggregation.
$config['system.performance']['css']['preprocess'] = FALSE;

// Disable JavaScript files aggregation.
$config['system.performance']['js']['preprocess'] = FALSE;

// Hide admin toolbar. Useful for themeing while logged in as admin.
// $settings['hide_admin_toolbar'] = TRUE;

Click here to see the contents of the default.services.local.yml file

parameters:
  http.response.debug_cacheability_headers: true
  # Disable twig debugging and auto reload, plus enable twig caching.
  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

Testing settings with unit tests

Vortex provides a set of unit tests that ensure that the settings apply correctly per environment type. These tests are expected to be maintained within your project, ensuring that settings activated by a specific environment type and environment variables are applied correctly.

After installing Vortex, run vendor/bin/phpunit --group=drupal_settings to run the tests for the settings provided by Vortex.

You may simply remove these tests if you do not want to maintain them.

1. Environment type constants definitions​

2. Site-specific settings​

3. Environment type detection​

Overriding environment type​

4. Per-environment overrides​

5. Inclusion of per-module settings​

6. Inclusion of local settings​

Testing settings with unit tests​