Defines the default configuration object.
Expanded class hierarchy of Config
class Config {
/**
* The maximum length of a configuration object name.
*
* Many filesystems (including HFS, NTFS, and ext4) have a maximum file name
* length of 255 characters. To ensure that no configuration objects
* incompatible with this limitation are created, we enforce a maximum name
* length of 250 characters (leaving 5 characters for the file extension).
*
* @see http://en.wikipedia.org/wiki/Comparison_of_file_systems
*/
const MAX_NAME_LENGTH = 250;
/**
* The name of the configuration object.
*
* @var string
*/
protected $name;
/**
* Whether the configuration object is new or has been saved to the storage.
*
* @var bool
*/
protected $isNew = TRUE;
/**
* The data of the configuration object.
*
* @var array
*/
protected $data;
/**
* The current runtime data ($data + $overrides from Config Context).
*
* @var array
*/
protected $overriddenData;
/**
* The storage used to load and save this configuration object.
*
* @var Drupal\Core\Config\StorageInterface
*/
protected $storage;
/**
* The configuration context used for this configuration object.
*
* @var \Drupal\Core\Config\Context\ContextInterface
*/
protected $context;
/**
* Whether the config object has already been loaded.
*
* @var bool
*/
protected $isLoaded = FALSE;
/**
* Constructs a configuration object.
*
* @param string $name
* The name of the configuration object being constructed.
* @param \Drupal\Core\Config\StorageInterface $storage
* A storage controller object to use for reading and writing the
* configuration data.
* @param \Drupal\Core\Config\Context\ContextInterface $context
* The configuration context used for this configuration object.
*/
public function __construct($name, StorageInterface $storage, ContextInterface $context) {
$this->name = $name;
$this->storage = $storage;
$this->context = $context;
}
/**
* Initializes a configuration object.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
public function init() {
$this->isLoaded = FALSE;
$this->overrides = array();
$this
->notify('init');
return $this;
}
/**
* Returns the name of this configuration object.
*
* @return string
* The name of the configuration object.
*/
public function getName() {
return $this->name;
}
/**
* Sets the name of this configuration object.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
public function setName($name) {
$this->name = $name;
return $this;
}
/**
* Validates the configuration object name.
*
* @throws \Drupal\Core\Config\ConfigNameException
*
* @see Config::MAX_NAME_LENGTH
*/
public static function validateName($name) {
// The name must be namespaced by owner.
if (strpos($name, '.') === FALSE) {
throw new ConfigNameException(format_string('Missing namespace in Config object name @name.', array(
'@name' => $name,
)));
}
// The name must be shorter than Config::MAX_NAME_LENGTH characters.
if (strlen($name) > self::MAX_NAME_LENGTH) {
throw new ConfigNameException(format_string('Config object name @name exceeds maximum allowed length of @length characters.', array(
'@name' => $name,
'@length' => self::MAX_NAME_LENGTH,
)));
}
// The name must not contain any of the following characters:
// : ? * < > " ' / \
if (preg_match('/[:?*<>"\'\\/\\\\]/', $name)) {
throw new ConfigNameException(format_string('Invalid character in Config object name @name.', array(
'@name' => $name,
)));
}
}
/**
* Returns whether this configuration object is new.
*
* @return bool
* TRUE if this config object does not exist in storage.
*/
public function isNew() {
if (!$this->isLoaded) {
$this
->load();
}
return $this->isNew;
}
/**
* Gets data from this config object.
*
* @param string $key
* A string that maps to a key within the configuration data.
* For instance in the following configuation array:
* @code
* array(
* 'foo' => array(
* 'bar' => 'baz',
* ),
* );
* @endcode
* A key of 'foo.bar' would return the string 'baz'. However, a key of 'foo'
* would return array('bar' => 'baz').
* If no key is specified, then the entire data array is returned.
*
* The configuration system does not retain data types. Every saved value is
* casted to a string. In most cases this is not an issue; however, it can
* cause issues with Booleans, which are casted to "1" (TRUE) or "0" (FALSE).
* In particular, code relying on === or !== will no longer function properly.
*
* @see http://php.net/manual/language.operators.comparison.php
*
* @return mixed
* The data that was requested.
*/
public function get($key = '') {
if (!$this->isLoaded) {
$this
->load();
}
if (!isset($this->overriddenData)) {
$this
->setOverriddenData();
}
if (empty($key)) {
return $this->overriddenData;
}
else {
$parts = explode('.', $key);
if (count($parts) == 1) {
return isset($this->overriddenData[$key]) ? $this->overriddenData[$key] : NULL;
}
else {
$value = NestedArray::getValue($this->overriddenData, $parts, $key_exists);
return $key_exists ? $value : NULL;
}
}
}
/**
* Replaces the data of this configuration object.
*
* @param array $data
* The new configuration data.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
public function setData(array $data) {
$this
->replaceData($data);
// A load would destroy the data just set (for example on import).
$this->isLoaded = TRUE;
return $this;
}
/**
* Replaces the data of this configuration object.
*
* This function is separate from setData() to avoid load() state tracking.
* A load() would destroy the replaced data (for example on import). Do not
* call set() when inside load().
*
* @param array $data
* The new configuration data.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
protected function replaceData(array $data) {
$this->data = $data;
$this
->resetOverriddenData();
return $this;
}
/**
* Sets overridden data for this configuration object.
*
* The overridden data only applies to this configuration object.
*
* @param array $data
* The overridden values of the configuration data.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
public function setOverride(array $data) {
$this->context
->setOverrides($this
->getName(), $data);
$this
->resetOverriddenData();
return $this;
}
/**
* Sets the current data for this configuration object.
*
* Merges overridden configuration data into the original data.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
protected function setOverriddenData() {
$this->overriddenData = $this->data;
$overrides = $this->context
->getOverrides($this
->getName());
if (is_array($overrides)) {
$this->overriddenData = NestedArray::mergeDeepArray(array(
$this->overriddenData,
$overrides,
), TRUE);
}
return $this;
}
/**
* Resets the current data, so overrides are re-applied.
*
* This method should be called after the original data or the overridden data
* has been changed.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
protected function resetOverriddenData() {
unset($this->overriddenData);
return $this;
}
/**
* Sets value in this config object.
*
* @param string $key
* Identifier to store value in config.
* @param string $value
* Value to associate with identifier.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
public function set($key, $value) {
if (!$this->isLoaded) {
$this
->load();
}
// Type-cast value into a string.
$value = $this
->castValue($value);
// The dot/period is a reserved character; it may appear between keys, but
// not within keys.
$parts = explode('.', $key);
if (count($parts) == 1) {
$this->data[$key] = $value;
}
else {
NestedArray::setValue($this->data, $parts, $value);
}
$this
->resetOverriddenData();
return $this;
}
/**
* Casts a saved value to a string.
*
* The configuration system only saves strings or arrays. Any scalar
* non-string value is cast to a string. The one exception is boolean FALSE
* which would normally become '' when cast to a string, but is manually
* cast to '0' here for convenience and consistency.
*
* Any non-scalar value that is not an array (aka objects) gets cast
* to an array.
*
* @param mixed $value
* A value being saved into the configuration system.
*
* @return string
* The value cast to a string or array.
*/
public function castValue($value) {
if (is_scalar($value) || $value === NULL) {
// Handle special case of FALSE, which should be '0' instead of ''.
if ($value === FALSE) {
$value = '0';
}
else {
$value = (string) $value;
}
}
else {
// Any non-scalar value must be an array.
if (!is_array($value)) {
$value = (array) $value;
}
// Recurse into any nested keys.
foreach ($value as $key => $nested_value) {
$value[$key] = $this
->castValue($nested_value);
}
}
return $value;
}
/**
* Unsets value in this config object.
*
* @param string $key
* Name of the key whose value should be unset.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
public function clear($key) {
if (!$this->isLoaded) {
$this
->load();
}
$parts = explode('.', $key);
if (count($parts) == 1) {
unset($this->data[$key]);
}
else {
NestedArray::unsetValue($this->data, $parts);
}
$this
->resetOverriddenData();
return $this;
}
/**
* Loads configuration data into this object.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
public function load() {
$this->isLoaded = FALSE;
$data = $this->storage
->read($this->name);
if ($data === FALSE) {
$this->isNew = TRUE;
$this
->replaceData(array());
}
else {
$this->isNew = FALSE;
$this
->replaceData($data);
}
$this
->notify('load');
$this->isLoaded = TRUE;
return $this;
}
/**
* Saves the configuration object.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
public function save() {
// Validate the configuration object name before saving.
static::validateName($this->name);
if (!$this->isLoaded) {
$this
->load();
}
$this->storage
->write($this->name, $this->data);
$this->isNew = FALSE;
$this
->notify('save');
return $this;
}
/**
* Deletes the configuration object.
*
* @return Drupal\Core\Config\Config
* The configuration object.
*/
public function delete() {
// @todo Consider to remove the pruning of data for Config::delete().
$this->data = array();
$this->storage
->delete($this->name);
$this->isNew = TRUE;
$this
->resetOverriddenData();
$this
->notify('delete');
return $this;
}
/**
* Retrieve the storage used to load and save this configuration object.
*
* @return \Drupal\Core\Config\StorageInterface
* The configuration storage object.
*/
public function getStorage() {
return $this->storage;
}
/**
* Dispatch a config event.
*/
protected function notify($config_event_name) {
$this->context
->notify($config_event_name, $this);
}
/**
* Merges data into a configuration object.
*
* @param array $data_to_merge
* An array containing data to merge.
*
* @return \Drupal\Core\Config\Config
* The configuration object.
*/
public function merge(array $data_to_merge) {
if (!$this->isLoaded) {
$this
->load();
}
// Preserve integer keys so that config keys are not changed.
$this
->replaceData(NestedArray::mergeDeepArray(array(
$this->data,
$data_to_merge,
), TRUE));
return $this;
}
}
Name | Modifiers | Type | Description | Overrides |
---|---|---|---|---|
Config:: |
protected | property | The configuration context used for this configuration object. | |
Config:: |
protected | property | The data of the configuration object. | |
Config:: |
protected | property | Whether the config object has already been loaded. | |
Config:: |
protected | property | Whether the configuration object is new or has been saved to the storage. | |
Config:: |
protected | property | The name of the configuration object. | |
Config:: |
protected | property | The current runtime data ($data + $overrides from Config Context). | |
Config:: |
protected | property | The storage used to load and save this configuration object. | |
Config:: |
public | function | Casts a saved value to a string. | |
Config:: |
public | function | Unsets value in this config object. | |
Config:: |
public | function | Deletes the configuration object. | |
Config:: |
public | function | Gets data from this config object. | |
Config:: |
public | function | Returns the name of this configuration object. | |
Config:: |
public | function | Retrieve the storage used to load and save this configuration object. | |
Config:: |
public | function | Initializes a configuration object. | |
Config:: |
public | function | Returns whether this configuration object is new. | |
Config:: |
public | function | Loads configuration data into this object. | |
Config:: |
constant | The maximum length of a configuration object name. | ||
Config:: |
public | function | Merges data into a configuration object. | |
Config:: |
protected | function | Dispatch a config event. | |
Config:: |
protected | function | Replaces the data of this configuration object. | |
Config:: |
protected | function | Resets the current data, so overrides are re-applied. | |
Config:: |
public | function | Saves the configuration object. | |
Config:: |
public | function | Sets value in this config object. | |
Config:: |
public | function | Replaces the data of this configuration object. | |
Config:: |
public | function | Sets the name of this configuration object. | |
Config:: |
protected | function | Sets the current data for this configuration object. | |
Config:: |
public | function | Sets overridden data for this configuration object. | |
Config:: |
public static | function | Validates the configuration object name. | |
Config:: |
public | function | Constructs a configuration object. |