Override CiviCRM Settings¶
CiviCRM provides a web-based interface for configuring its settings. This approach is easy-to-use for new administrators who maintain a single site, but it presents challenges for sophisticated administrators who manage many copies of CiviCRM. CiviCRM 4.1 introduced a new settings system which allows administrators to override some settings by managing a custom PHP file.
Further information about settings is on Settings Reference
Use Copied Databases by Overriding Server Directory and URL Settings¶
Some organizations run separate copies of CiviCRM for "production" ("live"), "testing", and/or "development." For example, if a developer wants to test a new feature, he might copy the database from the production system to the development system where he can safely test without interrupting normal users. Most of the settings should be copied exactly from production to development, but some server-specific settings – like the directory and URL settings – will always be different in production and development.
These server-specific settings are usually determined automatically during installation – but if you copy the database, then the administrator must fix them to match the new system. Two administrative forms are provided to allow administrators to manually edit these settings:
Administer > System Settings > Directories Administer > System Settings > Resource URLs
There are also some settings which can not be set from the administration user interface - but which can be overridden using this same technique. These include the Community Messages URL, and whether or not to allow users to download extensions (refer to Disable automatic installation of extensions for more details).
Override settings in civicrm.settings.php¶
If you regularly copy a production database to a test or development server, manually editing these settings may become cumbersome and error-prone. A faster alternative is to override the server-specific settings (e.g. directory and URL paths) by adding them to a local copy of the CiviCRM settings file (civicrm.settings.php). First ensure this line exists in civicrm.settings.php before any override settings.
Override Temporary Files directory¶
To override the Temporary Files directory for a test site, add these lines to civicrm.settings.php:
// Override the Temporary Files directory $civicrm_setting['domain']['customFileUploadDir'] = '/var/www/testing/sites/default/files/civicrm/upload';
In this example, note these three parts:
- Entity (
'domain'): This is a
domain-level setting. The vast majority of settings are
domain-level. A handful of settings are
contact-level. (Note: In CiviCRM <=4.6, this field used longer expressions like
URL Preferences. For backward compatibility, these are treated as aliases for
- Name (
'customFileUploadDir'): This is the name of the setting.
- Value (
'/var/www/testing/sites/default/files/civicrm/upload'): This is the new value of the setting.
List of Additional Settings¶
The table below shows some of the settings file "constants" which will override the database value if present in civicrm.settings.php and administrative settings field.
|Admin Field (Form)||Settings File Override Example|
|Temporary Files (System Settings > Directories)||
|Images (System Settings > Directories)||
|Custom Files (System Settings > Directories)||
|Custom Templates (System Settings > Directories)||
|Custom PHP Path Directory (System Settings > Directories)||
|Extensions Directory (System Settings > Directories)||
|CiviCRM Resource URL (System Settings > Resource URLs)||
|Image Upload URL (System Settings > Resource URLs)||
|Custom CiviCRM CSS URL (System Settings > Resource URLs)||
|Extensions Resource URL (System Settings > Resource URLs)||
|Disable display of Community Messages on home dashboard||
|Disable automatic download / installation of extensions||
|Set How long HTTP Requests could last for before timing out||
For a full list of settings, see the master settings PHP files
Incorrect Paths May Cause Unexpected Behaviors
HTTP Timeout Setting
From CiviCRM 5.15 onwards there is a hidden setting for the HTTP request timeout in seconds. The default for this is 5 seconds. Adjusting the timeout will affect both the page load times (lower time, pages will load faster), too low a timeout and CiviCRM status checks may not complete in time resulting in users seeing an incorrect status alert check failed warning message.