Legacy Documentation
You are using the documentation for version 4.3.8. Go here for the latest version.
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 sysem/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
EE_Config::$config¶ Array of all loaded config values
-
property
EE_Config::$is_loaded¶ Array of all loaded config files
-
EE_Config::item($item[, $index=''])¶ Parameters: - $item (string) – Config item name
- $index (string) – Index name
Returns: Config item value or NULL if not found
Return type: mixed
Fetch a config file item.
-
EE_Config::set_item($item, $value)¶ Parameters: - $item (string) – Config item name
- $value (string) – Config item value
Return type: void
Sets a config file item to the specified value.
-
EE_Config::slash_item($item)¶ Parameters: - $item (string) – config item name
Returns: Config item value with a trailing forward slash or NULL if not found
Return type: mixed
This method is identical to
item(), except it appends a forward slash to the end of the item, if it exists.
-
EE_Config::load([$file = ''[, $use_sections = FALSE[, $fail_gracefully = FALSE]]])¶ Parameters: - $file (string) – Configuration file name
- $use_sections (bool) – Whether config values shoud 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: TRUE on success, FALSE on failure
Return type: bool
Loads a configuration file.
-
EE_Config::site_url()¶ Returns: Site URL Return type: string 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.
-
EE_Config::update_site_prefs([$new_values = array()[, $site_ids = array()[, $find = ''[, $replace = '']]]])¶ Parameters: - $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.