ConfigService

Type
Class
Namespace
Craft
Inherits
Craft\ConfigService » Craft\BaseApplicationComponent » CApplicationComponent (opens new window) » CComponent (opens new window)
Implements
IApplicationComponent
Since
1.0

ConfigService provides APIs for retrieving the values of Craft’s config settings (opens new window), as well as the values of any plugins’ config settings.

An instance of ConfigService is globally accessible in Craft via {@link WebApp::config craft()->config}.

See also http://craftcms.com

View source (opens new window)

# Public Properties

Property Description
$behaviors (opens new window) array (opens new window) – The behaviors that should be attached to this component.

# Public Methods

Method Description
__call() (opens new window) Calls the named method which is not a class method.
__get() (opens new window) Returns a property value, an event handler list or a behavior based on its name.
__isset() (opens new window) Checks if a property value is null.
__set() (opens new window) Sets value of a component property.
__unset() (opens new window) Sets a component property to be null.
allowAutoUpdates() Returns whether the system is allowed to be auto-updated to the latest release.
asa() (opens new window) Returns the named behavior object.
attachBehavior() (opens new window) Attaches a behavior to this component.
attachBehaviors() (opens new window) Attaches a list of behaviors to the component.
attachEventHandler() (opens new window) Attaches an event handler to an event.
canGetProperty() (opens new window) Determines whether a property can be read.
canSetProperty() (opens new window) Determines whether a property can be set.
detachBehavior() (opens new window) Detaches a behavior from the component.
detachBehaviors() (opens new window) Detaches all behaviors from the component.
detachEventHandler() (opens new window) Detaches an existing event handler.
disableBehavior() (opens new window) Disables an attached behavior.
disableBehaviors() (opens new window) Disables all behaviors attached to this component.
enableBehavior() (opens new window) Enables an attached behavior.
enableBehaviors() (opens new window) Enables all behaviors attached to this component.
evaluateExpression() (opens new window) Evaluates a PHP expression or callback under the context of this component.
exists() Returns whether a config setting value exists, by a given name.
get() Returns a config setting value by its name.
getCacheDuration() Returns the value of the cacheDuration (opens new window) config setting, normalized into seconds.
getCpLoginPath() Returns the path to the CP’s Login page.
getCpLogoutPath() Returns the path to the CP’s Logout page.
getDbItem() Returns a config setting value by its name, pulled from craft/config/db.php.
getElevatedSessionDuration() Returns the configured elevated session duration in seconds.
getEventHandlers() (opens new window) Returns the list of attached event handlers for an event.
getIsInitialized() (opens new window) Checks if this application component has been initialized.
getLocalized() Returns a localized config setting value by its name.
getLoginPath() Returns the user login path based on the type of the current request.
getLogoutPath() Returns the user logout path based on the type of the current request.
getResourceTrigger() Returns the Resource Request trigger word based on the type of the current request.
getUserSessionDuration() Returns the configured user session duration in seconds, or null if there is none because user sessions should expire when the HTTP session expires.
hasEvent() (opens new window) Determines whether an event is defined.
hasEventHandler() (opens new window) Checks whether the named event has attached handlers.
hasProperty() (opens new window) Determines whether a property is defined.
init() (opens new window) Initializes the application component.
isInitialized() Checks if this application component has been initialized yet, or not.
maxPowerCaptain() Sets PHP’s memory limit to the maximum specified by the phpMaxMemoryLimit (opens new window) config setting, and gives the script an unlimited amount of time to execute.
omitScriptNameInUrls() Returns whether generated URLs should omit “index.php”, taking the omitScriptNameInUrls (opens new window) config setting value into account.
parseEnvironmentString() Parses a string for any environment variables (opens new window).
raiseEvent() (opens new window) Raises an event.
set() Overrides the value of a config setting to a given value.
usePathInfo() Returns whether generated URLs should be formatted using PATH_INFO, taking the usePathInfo (opens new window) config setting value into account.

# allowAutoUpdates()

Returns whether the system is allowed to be auto-updated to the latest release.

View source (opens new window)

Returns

boolean (opens new window)

Signature

public boolean allowAutoUpdates ( )

# exists()

Returns whether a config setting value exists, by a given name. If the config file is set up as a multi-environment config (opens new window), only values from config arrays that match the current request’s environment will be checked.

By default, exists() will check craft/config/general.php, and fall back on the default values specified in craft/app/etc/config/defaults/general.php. See Craft’s documentation (opens new window) for a full list of config settings that Craft will check for within that file.

If you want to get the config setting from a different config file (e.g. config/myplugin.php), you can specify its filename as a second argument. If the filename matches a plugin handle, get() will check for a craft/plugins/PluginHandle]/config.php file and use the array it returns as the list of default values.

if (craft()->config->exists('myConfigSetting', 'myplugin'))
{
    Craft::log('This site has some pretty useless config settings.');
}

View source (opens new window)

Arguments

Returns

boolean (opens new window) – Whether the config setting value exists.

Signature

public boolean exists ( $item, $file = \Craft\ConfigFile::General )

# get()

Returns a config setting value by its name. If the config file is set up as a multi-environment config (opens new window), only values from config arrays that match the current request’s environment will be checked and returned.

By default, get() will check craft/config/general.php, and fall back on the default values specified in craft/app/etc/config/defaults/general.php. See Craft’s documentation (opens new window) for a full list of config settings that Craft will check for within that file.

$isDevMode = craft()->config->get('devMode');

If you want to get the config setting from a different config file (e.g. config/myplugin.php), you can specify its filename as a second argument. If the filename matches a plugin handle, get() will check for a craft/plugins/PluginHandle]/config.php file and use the array it returns as the list of default values.

$myConfigSetting = craft()->config->get('myConfigSetting', 'myplugin');

View source (opens new window)

Arguments

Returns

mixed – The value of the config setting, or null if a value could not be found.

Signature

public mixed get ( $item, $file = \Craft\ConfigFile::General )

# getCacheDuration()

Returns the value of the cacheDuration (opens new window) config setting, normalized into seconds. The actual value of the cacheDuration config setting is supposed to be set using the PHP interval specification (opens new window).

craft()->config->get('cacheDuration'); // 'P1D'
craft()->config->getCacheDuration();   // 86400

View source (opens new window)

Returns

integer (opens new window) – The cacheDuration config setting value, in seconds.

Signature

public integer getCacheDuration ( )

# getCpLoginPath()

Returns the path to the CP’s Login page.

View source (opens new window)

Returns

string (opens new window) – The Login path.

Signature

public string getCpLoginPath ( )

# getCpLogoutPath()

Returns the path to the CP’s Logout page.

View source (opens new window)

Returns

string (opens new window) – The Logout path.

Signature

public string getCpLogoutPath ( )

# getDbItem()

DEPRECATED

Deprecated Deprecated in 2.0. Use {@link get() get('key', ConfigFile::Db)} instead.

Returns a config setting value by its name, pulled from craft/config/db.php.

View source (opens new window)

Arguments

  • $item (string (opens new window)) – The name of the config setting.
  • $default (mixed) – The default value to be returned in the event that the config setting isn’t set. Defaults to null.

Returns

string (opens new window) – The value of the config setting, or $default if a value could not be found.

Signature

public string getDbItem ( $item, $default = null )

# getElevatedSessionDuration()

Returns the configured elevated session duration in seconds.

View source (opens new window)

Returns

integer (opens new window), boolean (opens new window) – The elevated session duration in seconds or false if it has been disabled.

Signature

public integer, boolean getElevatedSessionDuration ( )

# getLocalized()

Returns a localized config setting value by its name. Internally, {@link get()} will be called to get the value of the config setting. If the value is an array, then only a single value in that array will be returned: the one that has a key matching the $localeId argument. If no matching key is found, the first element of the array will be returned instead.

This function is used for Craft’s “localizable” config settings:

View source (opens new window)

Arguments

Returns

mixed – The value of the config setting, or null if a value could not be found.

Signature

public mixed getLocalized ( $item, $localeId = null, $file = \Craft\ConfigFile::General )

# getLoginPath()

Returns the user login path based on the type of the current request. If it’s a front-end request, the loginPath (opens new window) config setting value will be returned. Otherwise the path specified in {@link getCpLoginPath()} will be returned.

View source (opens new window)

Returns

string (opens new window) – The login path.

Signature

public string getLoginPath ( )

# getLogoutPath()

Returns the user logout path based on the type of the current request. If it’s a front-end request, the logoutPath (opens new window) config setting value will be returned. Otherwise the path specified in {@link getCpLogoutPath()} will be returned.

View source (opens new window)

Returns

string (opens new window) – The logout path.

Signature

public string getLogoutPath ( )

# getResourceTrigger()

Returns the Resource Request trigger word based on the type of the current request. If it’s a front-end request, the resourceTrigger (opens new window) config setting value will be returned. Otherwise 'resources' will be returned.

View source (opens new window)

Returns

string (opens new window) – The Resource Request trigger word.

Signature

public string getResourceTrigger ( )

# getUserSessionDuration()

Returns the configured user session duration in seconds, or null if there is none because user sessions should expire when the HTTP session expires. You can choose whether the rememberedUserSessionDuration (opens new window) or userSessionDuration (opens new window) config setting should be used with the $remembered param. If rememberedUserSessionDuration’s value is empty (disabling the feature) then userSessionDuration will be used regardless of $remembered.

View source (opens new window)

Arguments

  • $remembered (boolean (opens new window)) – Whether the rememberedUserSessionDuration config setting should be used if it’s set. Default is false.

Returns

integer (opens new window), null (opens new window) – The user session duration in seconds, or null if user sessions should expire along with the HTTP session.

Signature

public integer, null getUserSessionDuration ( $remembered = false )

# maxPowerCaptain()

Sets PHP’s memory limit to the maximum specified by the phpMaxMemoryLimit (opens new window) config setting, and gives the script an unlimited amount of time to execute.

View source (opens new window)

Returns

null (opens new window)

Signature

public null maxPowerCaptain ( )

# omitScriptNameInUrls()

Returns whether generated URLs should omit “index.php”, taking the omitScriptNameInUrls (opens new window) config setting value into account. If the omitScriptNameInUrls config setting is set to true or false, then its value will be returned directly. Otherwise, omitScriptNameInUrls() will try to determine whether the server is set up to support index.php redirection. (See this help article (opens new window) for instructions.)

It does that by creating a dummy request to the site URL with the URI “/testScriptNameRedirect”. If the index.php redirect is in place, that request should be sent to Craft’s index.php file, which will detect that this is an index.php redirect-testing request, and simply return “success”. If anything besides “success” is returned (i.e. an Apache-styled 404 error), then Craft assumes the index.php redirect is not in fact in place.

Results of the redirect test request will be cached for the amount of time specified by the cacheDuration (opens new window) config setting.

View source (opens new window)

Returns

boolean (opens new window) – Whether generated URLs should omit “index.php”.

Signature

public boolean omitScriptNameInUrls ( )

# parseEnvironmentString()

Parses a string for any environment variables (opens new window). This method simply loops through all of the elements in the environmentVariables (opens new window) config setting’s value, and replaces any {tag}s in the string that have matching keys with their corresponding values.

View source (opens new window)

Arguments

Returns

string (opens new window) – The parsed string.

Signature

public string parseEnvironmentString ( $str )

# set()

Overrides the value of a config setting to a given value. By default, set() will update the config array that came from craft/config/general.php. See Craft’s documentation (opens new window) for a full list of config settings that Craft will check for within that file.

craft()->config->set('devMode', true);

If you want to set a config setting from a different config file (e.g. config/myplugin.php), you can specify its filename as a third argument.

craft()->config->set('myConfigSetting', 'foo', 'myplugin');

View source (opens new window)

Arguments

Returns

null (opens new window)

Signature

public null set ( $item, $value, $file = \Craft\ConfigFile::General )

# usePathInfo()

Returns whether generated URLs should be formatted using PATH_INFO, taking the usePathInfo (opens new window) config setting value into account. This method will usually only be called in the event that {@link omitScriptNameInUrls()} returns false (so “index.php” should be included), and it determines what follows “index.php” in the URL.

If it returns true, a forward slash will be used, making “index.php” look like just another segment of the URL (e.g. http://example.com/index.php/some/path). Otherwise the Craft path will be included in the URL as a query string param named ‘p’ (e.g. http://example.com/index.php?p=some/path).

If the usePathInfo config setting is set to true or false, then its value will be returned directly. Otherwise, usePathInfo() will try to determine whether the server is set up to support PATH_INFO. (See http://craftcms.com/help/enable-path-info for instructions.)

It does that by creating a dummy request to the site URL with the URI “/index.php/testPathInfo”. If the server supports it, that request should be sent to Craft’s index.php file, which will detect that this is an PATH_INFO-testing request, and simply return “success”. If anything besides “success” is returned (i.e. an Apache-styled 404 error), then Craft assumes the server is not set up to support PATH_INFO.

Results of the PATH_INFO test request will be cached for the amount of time specified by the cacheDuration (opens new window) config setting.

View source (opens new window)

Returns

boolean (opens new window) – Whether generaletd URLs should be formatted using PATH_INFO.

Signature

public boolean usePathInfo ( )