Config Class
The Config class provides a means to retrieve configuration preferences. These preferences can come from the system’s config file (system/user/config/config.php) or from your add-on’s custom config files.
Note: This class is initialized automatically by the system so there is no need to do it manually.
Working with the Config Class
Anatomy of a Config File
ExpressionEngine has one primary config file, located at system/user/config/config.php and add-ons can also contain additional config files located inside their directory. Make sure that you only use the primary configuration file when the config is on a per-install basis.
Note: If you do create your own config files use the same format as the primary one, storing your items in an array called $config. ExpressionEngine will intelligently manage these files so there will be no conflict even though the array has the same name (assuming an array index is not named the same as another).
Loading a Config File
Note: ExpressionEngine automatically loads the primary config file, so you will only need to load a config file if you have created your own.
There are two ways to load a config file:
Manual Loading
To load one of your custom config files you will use the following function within the controller that needs it:
ee()->config->load('filename');
Where filename is the name of your config file, without the .php file extension.
If you need to load multiple config files normally they will be merged into one master config array. Name collisions can occur, however, if you have identically named array indexes in different config files. To avoid collisions you can set the second parameter to TRUE and each config file will be stored in an array index corresponding to the name of the config file. Example:
// Stored in an array with this prototype: ee()->config['blog_settings'] = $config
ee()->config->load('blog_settings', TRUE);
Please see the section entitled Fetching Config Items below to learn how to retrieve config items set this way.
The third parameter allows you to suppress errors in the event that a config file does not exist:
ee()->config->load('blog_settings', FALSE, TRUE);
Fetching Config Items
To retrieve an item from your config file, use the following function:
ee()->config->item('item name');
Where item name is the $config array index you want to retrieve. For example, to fetch your language choice you’ll do this:
$lang = ee()->config->item('language');
The function returns NULL if the item you are trying to fetch does not exist.
If you are using the second parameter of the ee()->config->load function in order to assign your config items to a specific index you can retrieve it by specifying the index name in the second parameter of the ee()->config->item() function. Example:
// Loads a config file named blog_settings.php and assigns it to an index named "blog_settings"
ee()->config->load('blog_settings', TRUE);
// Retrieve a config item named site_name contained within the blog_settings array
$site_name = ee()->config->item('site_name', 'blog_settings');
// An alternate way to specify the same item:
$blog_config = ee()->config->item('blog_settings');
$site_name = $blog_config['site_name'];
Setting a Config Item
If you would like to dynamically set a config item or change an existing one, you can do so using:
ee()->config->set_item('item_name', 'item_value');
Where item_name is the $config array index you want to change, and item_value is its value.
Class Reference
class EE_Config
property $config
Array of all loaded config values
property $is_loaded
Array of all loaded config files
item($item[, $index=''])
| Parameter | Type | Description |
|---|---|---|
| $item | String |
Config item name |
| $index | String |
Index name |
| Returns | Mixed |
Config item value or NULL if not found |
Fetch a config file item.
set_item($item, $value)
| Parameter | Type | Description |
|---|---|---|
| $item | String |
Config item name |
| $value | String |
Config item value |
| Returns | Void |
Sets a config file item to the specified value.
slash_item($item)
| Parameter | Type | Description |
|---|---|---|
| $item | String |
config item name |
| Returns | Mixed |
Config item value with a trailing forward slash or NULL if not found |
This method is identical to item(), except it appends a forward slash to the end of the item, if it exists.
load([$file = ''[, $use_sections = FALSE[, $fail_gracefully = FALSE]]])
| Parameter | Type | Description |
|---|---|---|
| $file | String |
Configuration file name |
| $use_sections | Bool |
Whether config values should be loaded into their own section (index of the main config array) |
| $fail_gracefully | Bool |
Whether to return FALSE or to display an error message |
| Returns | Bool |
TRUE on success, FALSE on failure |
Loads a configuration file.
site_url()
| Parameter | Type | Description |
|---|---|---|
| Returns | String |
Site URL |
This method retrieves the URL to your site, along with the “index” value you’ve specified in the config file.
This method is normally accessed via the corresponding functions in the URL Helper.
update_site_prefs([$new_values = array()[, $site_ids = array()[, $find = ''[, $replace = '']]]])
| Parameter | Type | Description |
|---|---|---|
| $new_values | Array |
Associative array of keys and values to add to the config file |
| $site_ids | Array |
Array of site IDs to update. If left empty, uses current site ID. Alternatively, you can supply 'all' to update all sites. |
| $find | String |
String to find in site name (must not be using MSM). |
| $replace | String |
String to replace with in site name (must not be using MSM). |
Update the Site Preferences. Parses through an array of values and sees if they are valid site preferences. If so, we update the preferences in the database for this site. Anything left over is updated within the config files.
Note: If the new values passed via the first parameter are not found in the config file we will add them to the file. Effectively this lets us use this function instead of the “append” function used previously.