May 18, 2012

ExpressionEngine config file

One of the biggest takeaways from the EECI 2011 Conference in Brooklyn for me was the use of an ExpressionEngine config file in ExpressionEngine builds. Matt Weinberg from the Vector Media Group gave a great presentation titled 10 Ways to Rock ExpressionEngine. Using a config.php file allows you to control the numerous configuration options in ExpressionEngine from a single text file. This allows for quick and easy updates, instant provisioning of a new site install, and easy movement from server to server.

I spent some time with different ExpressionEngine config file approaches and have settled on a hybrid of some existing versions:

There are several other great resources out there for EE2 configuration:

I’m going to outline the different items that Pilotmade uses in our EE projects. We’re always tweaking this, so this approach is where we are in February of 2016.

The idea is to create a file titled config.php and place it at the root level of your site. Within that file you enter the following sections of configuration. Once the file is setup, it has to be included (required) from both /system/expressionengine/config/config.php and /system/expressionengine/config/database.php using the following code. Just place this at the bottom of each file.

require(realpath(dirname(__FILE__) . '/../../../config.php'));

Note: when you go to update your ExpressionEngine install, you MAY have to comment out this code or your upgrade MAY go into an endless loop. If that is the case, your standard config and database files MUST be valid and have the correct database credentials for the server you are upgrading on. 

1. ExpressionEngine config file Dynamic paths

The first thing to do is to set some dynamic file system paths based on the server the site is located on. This allows us to automatically set things like URL folder paths later on.

Note the $clean_urls array. You must set up the list of domain names you will be using for the site in order to keep things secure. Basically we’ll check against the approved list of domains in order to dynamically set our base site URL. If the $_SERVER[‘SERVER_NAME’] value doesn’t match an approved domain, it will default to the first domain in the array (which should probably be your production URL).

$protocol                         = (isset($_SERVER["HTTPS"]) && $_SERVER["HTTPS"] == "on") ? "https://" : "http://";

$clean_urls                       = array('site.com','site.local','site.dev');

if ( in_array($_SERVER['SERVER_NAME'], $clean_urls) ) {
    $base_url                     = $protocol . $_SERVER['SERVER_NAME'];
} else {
    $base_url                     = $protocol . $clean_urls[0];
}

$base_path                        = rtrim($_SERVER['DOCUMENT_ROOT'], "/");
$system_folder                    = "system";
$themes_folder                    = "themes";
$images_folder                    = "images";

$system_path                      = $base_path . "/" . $system_folder . "/";
$system_url                       = $base_url . "/" . $system_folder . "/";
$themes_path                      = $base_path . "/" . $themes_folder . "/";
$themes_url                       = $base_url . "/" . $themes_folder . "/";     
$images_path                      = $base_path . "/" . $images_folder . "/";
$images_url                       = $base_url . "/" . $images_folder . "/";

$user_agent                       = $_SERVER['HTTP_USER_AGENT'];

2. Environmental Variables (database)

This allows you to enter multiple database credentials based on the server you are on. This makes it very easy to move from one server to another when you launch a new site. This method uses the IP address of the server to determine which credentials to use. Depending on your setup, you may need to use a different method to check the server (hostname etc.), especially if your development and production installs are on the same server.

switch ( $_SERVER['SERVER_ADDR'] ) {

/* Local DB Config */ 
case '127.0.0.1' : 
$db['expressionengine']['hostname'] = "localhost";
$db['expressionengine']['username'] = "username";
$db['expressionengine']['password'] = "password";
$db['expressionengine']['database'] = "database";
$env_global_vars = array(
    'global:env' => 'local'
);
break;

/* Development DB Config */
case '111.222.333.444' :
$db['expressionengine']['hostname'] = "localhost";
$db['expressionengine']['username'] = "username";
$db['expressionengine']['password'] = "password";
$db['expressionengine']['database'] = "database";
$env_global_vars = array(
    'global:env' => 'dev'
);
break; 

/* Production DB Config */
case '444.333.222.111' : 
$db['expressionengine']['hostname'] = "localhost";
$db['expressionengine']['username'] = "username";
$db['expressionengine']['password'] = "password";
$db['expressionengine']['database'] = "database";
$env_global_vars = array(
    'global:env' => 'prod'
);
break;

}

3. Debugging and Performance

Quick access to debugging controls. This is always helpful if something goes awry and your site stops showing up.

$config['show_profiler']                = 'n'; # y/n
$config['template_debugging']           = 'n'; # y/n
$config['debug']                        = '1'; # 0: no PHP/SQL errors shown. 1: Errors shown to Super Admins. 2: Errors shown to everyone.
$config['disable_all_tracking']         = 'y'; # y/n
$config['enable_sql_caching']           = 'n'; # Cache Dynamic Channel Queries?
$config['email_debug']                  = 'n'; # y/n
$config['autosave_interval_seconds']    = '0'; # Disabling entry autosave
$config['gzip_output']                  = 'y'; # y/n

4. General Paths

Standard site paths.

$config['index_page']             = "/";
$config['site_index']             = "/";
$config['base_url']               = $base_url . "/";
$config['site_url']               = $config['base_url'];
$config['cp_url']                 = $system_url . "/index.php";
$config['theme_folder_path']      = $themes_path;
$config['theme_folder_url']       = $themes_url;

5. Universal Database Settings

These are mostly the values from the standard database.php file.

$db['expressionengine']['dbdriver']  = "mysql";
$db['expressionengine']['dbprefix']  = "exp_";
$db['expressionengine']['pconnect']  = FALSE;
$db['expressionengine']['swap_pre']  = "exp_";
$db['expressionengine']['db_debug']  = FALSE;
$db['expressionengine']['cache_on']  = TRUE;
$db['expressionengine']['autoinit']  = FALSE;
$db['expressionengine']['char_set']  = "utf8";
$db['expressionengine']['dbcollat']  = "utf8_general_ci";
$db['expressionengine']['cachedir']  = $system_path ."expressionengine/cache/db_cache/";

6. Template Preferences

This lets you set up the defaults for how templates are treated. I save templates as flat files so I have that set to yes. I also move the templates folder out of /system/ into the root level of the site. Just make sure you have an htaccess file set to deny from all so your templates folder isn’t open to the world.

$config['strict_urls']               = "y";
$config['site_404']                  = "site/404";
$config['save_tmpl_revisions']       = "y";
$config['save_tmpl_files']           = "y";
$config['tmpl_file_basepath']        = $base_path . "/assets/templates/";
$config['hidden_template_indicator'] = "_";

7. Member Directory paths and URLs

Moving from server to server means paths get will likely get updated. Having these dynamic is a big help.

$config['emoticon_path']        = $images_url . "smileys/";
$config['captcha_path']         = $images_path . "captchas/";
$config['captcha_url']          = $images_url . "captchas/";
$config['avatar_path']          = $images_path . "avatars/";
$config['avatar_url']           = $images_url . "avatars/";
$config['photo_path']           = $images_path . "member_photos/";
$config['photo_url']            = $images_url . "member_photos/";
$config['sig_img_path']         = $images_path . "signature_attachments/";
$config['sig_img_url']          = $images_url . "signature_attachments/";
$config['prv_msg_upload_path']  = $images_path . "pm_attachments/";

8. Global Variables

This section allows you to set up some really handy global variables to use throughout your site. You can easily add to this to create nice shortcuts during development.

$default_global_vars = array(

	// Tag parameters - Short hand tag params
	'global:disable_default'   => 'disable="categories|pagination|member_data"',
	'global:disable_all'       => 'disable="categories|custom_fields|member_data|pagination"',
	'global:cache'        => 'cache="yes" refresh="10"',
	'-global:cache'       => '-cache="yes" refresh="10"', // disable by adding a '-' to the front of the global

	// Date and time - Short hand date and time
	'global:date_time'          => '%g:%i %a',
	'global:date_short'         => '%F %d, %Y',
	'global:date_full'          => '%F %d %Y, %g:%i %a',

	'global:isipad'    => (bool) strpos($user_agent,'iPad'),
	'global:isiphone'   => (bool) strpos($user_agent,'iPhone')

);

// Make this global so we can add some of the config variables here

global $assign_to_config;

if(!isset($assign_to_config['global_vars'])) {
	$assign_to_config['global_vars'] = array();
}

$assign_to_config['global_vars'] = array_merge($assign_to_config['global_vars'], $default_global_vars, $env_global_vars);

Using an ExpressionEngine config.php file can speed up initial site installs, simplify server moves, and add convenient ExpressionEngine configuration options. Definitely worth the effort.