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 supposed to be maintained within your project, ensuring that settings activated by specific environments and environment variables are applied accurately.
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 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 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_TEST')) {
define('ENVIRONMENT_TEST', 'test');
}
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('MARIADB_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;
// Enable state cache.
$settings['state_cache'] = 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('MARIADB_DATABASE') ?: 'drupal',
'username' => getenv('MARIADB_USERNAME') ?: 'drupal',
'password' => getenv('MARIADB_PASSWORD') ?: 'drupal',
'host' => getenv('MARIADB_HOST') ?: 'localhost',
'port' => getenv('MARIADB_PORT') ?: '',
'prefix' => '',
'driver' => 'mysql',
],
],
];
////////////////////////////////////////////////////////////////////////////////
/// ENVIRONMENT DETECTION ///
////////////////////////////////////////////////////////////////////////////////
// Load environment-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.
//
// 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';
}
if (file_exists($app_root . '/' . $site_path . '/services.local.yml')) {
$settings['container_yamls'][] = $app_root . '/' . $site_path . '/services.local.yml';
}
// @codeCoverageIgnoreEnd
- Environment constants definitions
- Site-specific settings
- Environment detection
- Per-environment overrides
- Inclusion of generated Settings
- Inclusion of local settings
1. Environment constants definitions
Constants for various environments are defined here. These can be used to alter site behavior based on the active environment.
Available constants include:
ENVIRONMENT_LOCAL
ENVIRONMENT_CI
ENVIRONMENT_PROD
ENVIRONMENT_TEST
ENVIRONMENT_DEV
These are later used to set $settings['environment']
variable, which can be
used in the modules and outside scripts to target code execution to specific
environments.
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
The $VORTEX_PROVISION_ENVIRONMENT
environment variable can be utilized
within post-provision custom scripts, allowing targeted code execution based
on specific environments. 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 environments.
Use per-module settings files in the web/site/default/includes
directory to
override per-module settings, including per-environment overrides.
3. Environment detection
This section uses known hosting platform mechanisms to determine in which
environment the site currently runs. The result is stored in the
$settings['environment']
variable.
By default, $settings['environment']
is set to ENVIRONMENT_LOCAL
.
This value is then overridden by the environment detection logic.
In any hosting environment, the default value of $settings['environment']
changes to ENVIRONMENT_DEV
, while further refinements designate more
advanced environments.
Environment detection override
It is also possible to force specific environment by setting
DRUPAL_ENVIRONMENT
environment variable. In this case, the environment
detection will take place and will load any additional hosting platform settings,
but the final value of $settings['environment']
will be set to the value of
DRUPAL_ENVIRONMENT
variable.
This is useful in cases where a certain behavior is required for a specific environment, but the environment detection logic does not provide it. Or as a temporary override during testing.
4. Per-environment overrides
Configurations in this section alter the site's behavior based on the environment. Out-of-the-box, Vortex provides overrides for CI and Local environments.
You can add additional overrides for other environments as needed.
5. Inclusion of per-module settings
This section includes any additional module-specific settings from the
/includes
directory.
Vortex ships with settings overrides for several popular contributed modules used in almost every project.
The per environment overrides for modules should be also placed into files
in the /includes
directory.
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.
Testing settings with unit tests
Vortex provides a set of unit tests that ensure that the settings apply correctly per environment. These tests are supposed to be maintained within your project, ensuring that settings activated by specific environments and environment variables are applied accurately.
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.