Configuring Settings.php
Detailed information about configuring your Drupal database settings.
Contributors: Maximo Mena, Andrew Mallis.
Discuss in our Forum Discuss in SlackThe Drupal system configuration in code is set in the sites/default/settings.php
file.
Drupal 8
Drupal 8 sites on Pantheon run an unmodified version of core, bundled with a custom settings.php
file that includes the necessary settings.pantheon.php
. If the stock settings.php
file is used in place of the bundled file, the site will stop working on Pantheon.
Drupal 8.8
Drupal 8.7.x sites that have modified the config_sync_directory
value in settings.php
may see this error when upgrading to Drupal 8.8.x:
CONFIGURATION SYNC DIRECTORY
The directory sites/default/config does not exist.
To resolve (or avoid before upgrading), update the modified code as follows:
Locate:
settings.php$config_directories = array( CONFIG_SYNC_DIRECTORY => dirname(DRUPAL_ROOT) . '/config', );
Replace it with:
settings.php$settings['config_sync_directory'] = dirname(DRUPAL_ROOT) . '/config';
Note: example-drops-8-composer
(the starting template for all Composer-managed sites on Pantheon) includes this configuration in settings.php
. Any site built from this example (e.g., using either the No CI workflow or the Build Tools workflow) will need to be updated.
Drupal 7 and Earlier
For Drupal 7 and earlier, Pantheon uses a variant of Pressflow Drupal to allow the server to automatically specify configuration settings, such as the database configuration without editing settings.php
. Permissions are handled automatically by Pantheon, so you can customize settings.php
like any other site code.
Pantheon Articles on settings.php
The following articles include techniques and configurations for settings.php
on Pantheon:
- Reading Pantheon Environment Configuration (including domain_access)
- Object Cache (formerly Redis) for Drupal or WordPress
- Platform and Custom Domains
- Configure Redirects
- SSO and Identity Federation (LDAP TLS certificate configuration)
Local Database Configuration for Development
Warning
You should never put the database connection information for a Pantheon database within your settings.php
file. These credentials will change. If you are having connection errors, make sure you are running Pressflow core. This is a requirement.
Use these configuration snippets to specify a local configuration that will be ignored by Pantheon, such as database credentials.
Drupal 8
Configure environment-specific settings within the settings.local.php
file, which is ignored by git in our Drupal 8 upstream. Modifying the bundled settings.php
file is not necessary, as it already includes settings.local.php
if one exists.
// Local development configuration.
if (!defined('PANTHEON_ENVIRONMENT')) {
// Database.
$databases['default']['default'] = array(
'database' => 'DATABASE',
'username' => 'USERNAME',
'password' => 'PASSWORD',
'host' => 'localhost',
'driver' => 'mysql',
'port' => 3306,
'prefix' => '',
);
}
The HASH_SALT
value should also be set within settings.local.php
. See Drush script: Quickstart
To use the Pantheon HASH_SALT
in your local site (not necessary), you can get it via Terminus:
terminus drush <site>.<env> -- ev 'return getenv("DRUPAL_HASH_SALT")'
Drupal 8 will not run locally without a hash salt, but it need not be the same one set on the Pantheon platform; any sufficiently long random string will do. Make sure to set one in settings.local.php
:
$settings['hash_salt'] = '$HASH_SALT';
Trusted Host Setting
A warning within /admin/reports/status
will appear when the trusted_host_patterns
setting is not configured. This setting protects sites from HTTP Host header attacks. However, sites running on Pantheon are not vulnerable to this specific attack and the warning can be safely ignored. If you would like to resolve the warning, use the following configuration:
Note
Replace yoursite\.com
with custom domain(s) added within the Site Dashboard, adjusting patterns as needed. Be sure to escape any characters that need to be escaped in regular expressions, including dots (.
). If you're using the Drupal 8 redirects from our Configure Redirects doc, don't use this snippet as it conflicts.
if (defined('PANTHEON_ENVIRONMENT')) {
if (in_array($_ENV['PANTHEON_ENVIRONMENT'], array('dev', 'test', 'live'))) {
$settings['trusted_host_patterns'][] = "{$_ENV['PANTHEON_ENVIRONMENT']}-{$_ENV['PANTHEON_SITE_NAME']}.pantheon.io";
$settings['trusted_host_patterns'][] = "{$_ENV['PANTHEON_ENVIRONMENT']}-{$_ENV['PANTHEON_SITE_NAME']}.pantheonsite.io";
# Replace value with custom domain(s) added in the site Dashboard
$settings['trusted_host_patterns'][] = '^.+\.yoursite\.com$';
$settings['trusted_host_patterns'][] = '^yoursite\.com$';
}
}
Drupal 7
// Local development configuration.
if (!defined('PANTHEON_ENVIRONMENT')) {
// Database.
$databases['default']['default'] = array(
'database' => 'DATABASE',
'username' => 'USERNAME',
'password' => 'PASSWORD',
'host' => 'localhost',
'driver' => 'mysql',
'port' => 3306,
'prefix' => '',
);
}
Drupal 6
// Local development configuration.
if (!defined('PANTHEON_ENVIRONMENT')) {
// Database.
$db_url = 'mysql://username:password@localhost/databasename';
$db_prefix = '';
}
Frequently Asked Questions
Can I delete the default.settings.php file?
Yes, but only if at least one other file (e.g. settings.php
) is present within the sites/default
directory. Otherwise, the existing symlink to sites/default/files
will be invalid.
How can I write logic based on the Pantheon server environment?
Depending on your use case, there are three possibilities:
For web only actions, like redirects, check for the existence of
$_ENV['PANTHEON_ENVIRONMENT']
. If it exists, it will contain a string with the current environment (Dev, Test, Live, or Multidev environment names if they are present). See our redirects guide for examples.Note
$_SERVER
is not generally available from the command line so logic should check for that when used, and avoid using$_SERVER['SERVER_NAME']
and$_SERVER['SERVER_PORT']
.For actions that should take place on every environment, such as object caching, use the constant
PANTHEON_ENVIRONMENT
. Again, it will contain Dev, Test, or Live. See our Object Cache guide for examples.For Actions that require access to protected services like Object Cache or the site database, you can use the
$_ENV
superglobal. Please review our guide on Reading Pantheon Environment Configuration for more information, or see our Object Cache guide for examples.
As an example, here's how you can hard-code your Drupal 7 caching configuration and Google Analytics based on the environment. To learn more, see Defining variables in a site's settings.php $conf array.
// All Pantheon Environments.
if (defined('PANTHEON_ENVIRONMENT')) {
// Drupal caching in development environments.
if (!in_array(PANTHEON_ENVIRONMENT, array('test', 'live'))) {
// Anonymous caching.
$conf['cache'] = 0;
// Block caching - disabled.
$conf['block_cache'] = 0;
// Expiration of cached pages - none.
$conf['page_cache_maximum_age'] = 0;
// Aggregate and compress CSS files in Drupal - off.
$conf['preprocess_css'] = 0;
// Aggregate JavaScript files in Drupal - off.
$conf['preprocess_js'] = 0;
}
// Drupal caching in test and live environments.
else {
// Anonymous caching - enabled.
$conf['cache'] = 1;
// Block caching - enabled.
$conf['block_cache'] = 1;
// Expiration of cached pages - 15 minutes.
$conf['page_cache_maximum_age'] = 900;
// Aggregate and compress CSS files in Drupal - on.
$conf['preprocess_css'] = 1;
// Aggregate JavaScript files in Drupal - on.
$conf['preprocess_js'] = 1;
}
// Minimum cache lifetime - always none.
$conf['cache_lifetime'] = 0;
// Cached page compression - always off.
$conf['page_compression'] = 0;
if (PANTHEON_ENVIRONMENT == 'dev') {
// Google Analytics.
$conf['googleanalytics_account'] = 'UA-XXXXXXXX-X';
}
else if (PANTHEON_ENVIRONMENT == 'test') {
// Google Analytics.
$conf['googleanalytics_account'] = 'UA-XXXXXXXX-Y';
}
else if (PANTHEON_ENVIRONMENT == 'live') {
// Google Analytics.
$conf['googleanalytics_account'] = 'UA-XXXXXXXX-Z';
}
}
Why does Drupal report that settings.php is not protected? I can't change the permissions on settings.php.
If you do not have a settings.php
file in your codebase, you'll see the following message on /admin/reports/status
:
Configuration file: Not protected. The file sites/default/settings.php
is not protected from modifications and poses a security risk. You must change the file's permissions to be non-writable.
Technically, it's possible to have a functioning Drupal site without settings.php
on Pantheon, but this breaks compatibility with many modules and tools. Therefore, it's strongly recommended to either copy the default.settings.php
file to settings.php
or create an empty settings.php
file.
Should I include settings.php in my site import?
It depends on your site configuration. Stripping commented-out or non-functional code from your existing settings.php
file, leaving only known good functional configurations is a best practice and makes it easier to troubleshoot.
Where do I specify database credentials?
Pantheon automatically injects database credentials into the site environment; if you hard code database credentials, you will break the Pantheon workflow.
Where do I set or modify the drupal_hash_salt value in Drupal 7?
There can be an occasion when you may need to set the hash salt to a specific value. If you install Drupal 7, it will create a drupal_hash_salt
value for you, but if you want to use a different one, you can edit settings.php
before installation. Pantheon uses Pressflow to automatically read the environmental configuration and the Drupal 7 hash salt is stored as part of the Pressflow settings.
// All Pantheon Environments.
if (defined('PANTHEON_ENVIRONMENT')) {
// Set your custom hash salt value.
$custom_hash_salt = '';
// Extract Pressflow settings into a php object.
$pressflow_settings = json_decode($_SERVER['PRESSFLOW_SETTINGS']);
$pressflow_settings->drupal_hash_salt = $custom_hash_salt;
$_SERVER['PRESSFLOW_SETTINGS'] = json_encode($pressflow_settings);
}
Where can I get a copy of a default.settings.php?
- Drupal 8 - https://github.com/pantheon-systems/drops-8/blob/master/sites/default/default.settings.php
- Drupal 7 - https://github.com/pantheon-systems/drops-7/blob/master/sites/default/default.settings.php
- Drupal 6 - https://github.com/pantheon-systems/drops-6/blob/master/sites/default/default.settings.php
Where can I find examples of Pantheon settings.php?
You can view examples at the pantheon-settings-examples repo.
Are table prefixes supported?
Pantheon injects the database configuration dynamically during bootstrap. In the PRESSFLOW_SETTINGS
variable, the appropriate database connection information is passed in based upon the environment (Dev/Test/Live).
You can technically use database prefixes, but Pantheon will not support database prefixes. As a best practice, allow Pantheon to populate your database configuration settings.
Why is the Status tab for my Drupal 7 site showing that my configuration file is not protected and that I need to create a settings.php file?
Drupal 7 doesn't ship with a settings.php
in place; as the error suggests, you should make a copy of the default.settings.php
and rename it settings.php
. Once you have created a settings.php
file, the settings.php
area of the report should change to green.
Drupal 7 sites that plan to use Drush should have a settings.php
file.
Can I edit settings.pantheon.php?
No; settings.pantheon.php
is for Pantheon's use only and you should only modify the settings.php
file. The settings.pantheon.php
file may change in future updates, and modifying it would cause conflicts.
How do I enable ionCube Decoder support?
If you are using a licensed plugin that requires ionCube Decoder support, first ensure you are running PHP 7.1. Please note later PHP versions do not currently support ionCube.
Enable ionCube Decoder support site-wide by adding this line to
settings.php
:settings.phpini_set('ioncube.loader.encoded_paths', '/');
(More information can be found in our PHP 7.1 & ionCube Decoder Now Available for All Sites on Pantheon blog post.)
Troubleshooting
Request to a Remote API Does Not Return Expected Response
The PHP 5.5 default is &
and the PHP 5.3 default is &
.
If the API expects &
as an argument separator but receives &
(for example, when using http_build_query), you can override the default arg_separator.output value by adding the following line to settings.php
:
ini_set('arg_separator.output', '&');
Drush Error: "No Drupal site found", "Could not find a Drupal settings.php file", or missing system information from status
Could not find a Drupal settings.php file at ./sites/default/settings.php
To resolve, add a default or empty sites/default/settings.php
to your site's code.
Error: "The provided host name is not valid for this server."
This error comes from a feature in Drupal 8 designed to protect against HTTP HOST Header attacks. Drupal 8 allows you to specify "trusted host patterns," which specify a set of domains that incoming requests must match.
If you see this error, you need to update your trusted host patterns in settings.php
and add your new domain(s) to the $settings['trusted_host_patterns']
array.
By default, Pantheon's environment is configured to not allow any non-trusted hosts. Trusted hosts are added via the PANTHEON_ENVIRONMENT
variable in settings.php
here:
/**
* "Trusted host settings" are not necessary on Pantheon; traffic will only
* be routed to your site if the host settings match a domain configured for
* your site in the dashboard.
*/
if (isset($_ENV['PANTHEON_ENVIRONMENT'])) {
$settings['trusted_host_patterns'][] = '.*';
}