Configuring ExpressionEngine is a black art; the layout of configuration values in the control panel isn’t particularly well thought out. Some values are on one page, others are on a different page, and the whole thing needs much more logical grouping.
Additionally, storing configuration in the database has its own set of downfalls: deploying sites is a real pain because DB values need to be updated and some of them are even encoded in the database. Accessing and modifying them quickly becomes cumbersome.
Thankfully, EE can be configured through an alternative method. You can override pretty much any configuration value in ExpressionEngine in the expressionengine/config/config.php file.
But why would you want to? As I’ve just stated, most of ExpressionEngine can be configured in some way or another from within your config file. This allows you to contain your entire system’s configuration in one accessible place, making it simple and brief to change a system setting.
Additionally, having config values in a file rather than the database makes deploying your EE website much, much easier. Using a few clever techniques can help you run your site in multiple environments and on different servers without having to make any changes between deploys.
One of the really beautiful things about holding your system values in your config file is that your entire’s system can be held in version control. I’ll discuss the merits of using a version control system with EE entirely some other time, but the ability to switch between versions, use branching and distributing files to others with ease barely scratch the surface. The number of benefits is staggering.
Let’s see some code. The following is an example of a very basic config.php that can be used for simple, one server ExpressionEngine projects.
<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
/* ExpressionEngine Configuration
-------------------------------------------------------------------*/
$config['app_version'] = "213";
$config['license_number'] = "0000-0000-0000-0000";
$config['debug'] = "1";
$config['install_lock'] = "";
$config['system_folder'] = "system";
$config['is_system_on'] = "y";
$config['allow_extensions'] = "y";
$config['site_url'] = "http://".$_SERVER['HTTP_HOST'];
$config['server_path'] = FCPATH;
$config['cp_url'] = $config['site_url'] . ‘/system/‘;
$config['theme_folder_url'] = $config['site_url']."/themes/";
$config['theme_folder_path'] = $config['server_path']."/themes/";
$config['save_tmpl_files'] = "y";
$config['tmpl_file_basepath'] = $config['server_path']."/templates/";
/* CodeIgniter Configuration
-------------------------------------------------------------------*/
$config['base_url'] = $config['site_url'];
$config['uri_protocol'] = 'AUTO';
$config['language'] = 'english';
$config['charset'] = 'UTF-8';
$config['subclass_prefix'] = 'EE_';
$config['permitted_uri_chars'] = 'a-z 0-9~%.:_\\-';
$config['enable_query_strings'] = FALSE;
$config['directory_trigger'] = 'D';
$config['controller_trigger'] = 'C';
$config['function_trigger'] = 'M';
$config['log_threshold'] = 0;
$config['log_path'] = '';
$config['log_date_format'] = 'Y-m-d H:i:s';
$config['time_reference'] = 'local';
/* End of file config.php */
/* Location: ./system/expressionengine/config/config.php */
It looks like a lot of code, but if you take a brief look it’s actually all very simple. Firstly, I’ve cleaned up the original config file by removing most of the comments and grouping the file up by ExpressionEngine configuration and CodeIgniter configuration. As our file gets bigger we can group even further.
I’ve also removed many of the configuration values that we won’t be touching. You’ll be surprised at how few configuration values we actually need to use in our config file; and that includes CodeIgniter.
Our first few lines of code:
$config['app_version'] = "213";
$config['license_number'] = "0000-0000-0000-0000";
$config['debug'] = "1";
$config['install_lock'] = "";
$config['system_folder'] = "system";
$config['is_system_on'] = "y";
These are the basic, default ExpressionEngine configuration variables. The current EE version, your license number, debug settings, install lock, name of the system folder and the current system enabled status. It’s all self-explanatory.
You’ll almost always want to enable extensions (and can sometimes get caught out if you don’t!) so we’ll do that in our config file to make sure it happens.
$config['allow_extensions'] = "y";
We’ll also semi-dynamically set our server path and URL, so that if we decide to update our domain name, or push the site live, our configuration changes will be minimal. We can use the HTTP_HOST server variable value to get the current domain. Likewise, we can use CodeIgniter’s FCPATH to get the path to our front controller. In most cases this is your index.php file.
$config['site_url'] = "http://".$_SERVER['HTTP_HOST'];
$config['server_path'] = FCPATH;
Setting these means that we can use them later in the config file. Lets make some other paths and URLs dynamic. The path and URL to the themes directory is really important, so let’s set them to be relative to our site_url and server_path.
We will also set our CP URL to be relative to our aforementioned site URL. Finally, we can enable saving templates as files from the config file and set the directory dynamically.
$config['cp_url'] = $config['site_url'] . '/system';
$config['theme_folder_url'] = $config['site_url']."/themes/";
$config['theme_folder_path'] = $config['server_path']."/themes/";
$config['save_tmpl_files'] = "y";
$config['tmpl_file_basepath'] = $config['server_path']."/templates/";
Using your config.php file to configure and maintain your ExpressionEngine install is easy. While this is a simple example, it’s immediately practical, and can help you get on your way to better EE installations.
In a future post I’ll demonstrate how you can create a multi-server setup in your config.php file and let ExpressionEngine be truly dynamic.
Thursday, April 7, 2011 at 10:00AM