class Config

BackdropWebTestCase::refreshVariables in core/modules/simpletest/backdrop_web_test_case.php

Refresh the in-memory set of variables and state values. Useful after a page request is made that changes a variable in a different thread.

block_admin_list in core/modules/block/block.admin.inc

Page callback; Display a list of all custom blocks.

ckeditor5_ckeditor5_plugins in core/modules/ckeditor5/ckeditor5.module

Implements hook_ckeditor5_plugins().

ckeditor5_get_config in core/modules/ckeditor5/ckeditor5.module

Editor JS settings callback; Add CKEditor config to the page for a format.

ColorTestCase::setUp in core/modules/color/tests/color.test

Sets up a Backdrop site for running functional and integration tests.

... See full list

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;

  /**
   * Any overrides specified for this configuration object.
   *
   * @var array
   */
  protected $overrides;

  /**
   * The state of validation on this object.
   *
   * This value is set to TRUE by Config::validate() and is reset to FALSE after
   * any change to the $data variable.
   */
  protected $validated = FALSE;

  /**
   * The storage used to load and save this configuration object.
   *
   * @var ConfigStorageInterface
   */
  protected $storage;

  /**
   * The configuration context used for this configuration object.
   *
   * @var ConfigStorageInterface
   */
  protected $context;

  /**
   * Whether the configuration 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 ConfigStorageInterface $storage
   *   A storage controller object to use for reading and writing the
   *   configuration data.
   */
  public function __construct($name, ConfigStorageInterface $storage) {
    global $config;

    $this->name = $name;
    $this->storage = $storage;
    $this->overrides = isset($config[$name]) ? $config[$name] : NULL;
  }

  /**
   * Initializes a configuration object.
   *
   * @return Config
   *   The configuration object.
   */
  public function init() {
    $this->isLoaded = FALSE;
    return $this;
  }

  /**
   * Initializes a configuration object with pre-loaded data.
   *
   * @param array $data
   *   Array of loaded data for this configuration object.
   *
   * @return Config
   *   The configuration object.
   */
  public function initWithData(array $data) {
    $this->isLoaded = TRUE;
    $this->isNew = FALSE;
    $this->replaceData($data);
    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.
   *
   * @param string $name
   *   The name of the configuration object.
   *
   * @return Config
   *   The configuration object.
   */
  public function setName($name) {
    $this->name = $name;
    return $this;
  }

  /**
   * Validates the configuration object name.
   *
   * @param string $name
   *   The name of the configuration object.
   *
   * @throws 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,
      )));
    }
  }

  /**
   * Validate the full contents of the configuration data.
   *
   * This method is not automatically called when Config::setData() is called.
   * Because validation is a potentially expensive operation, you should call
   * this only when expecting potential problems in the provided data, such as
   * when validating user-provided imports.
   *
   * @throws ConfigValidateException
   */
  public function validateData() {
    if (!$this->validated) {
      $config_info = config_get_info($this->getName());
      module_invoke_all('config_data_validate', $this, $config_info);
      $this->validated = TRUE;
    }
  }

  /**
   * Returns whether this configuration object is new.
   *
   * @return bool
   *   TRUE if this configuration object does not exist in storage.
   */
  public function isNew() {
    if (!$this->isLoaded) {
      $this->load();
    }
    return $this->isNew;
  }

  /**
   * Check if a particular config key is overridden.
   *
   * @param string $key
   *   A string that maps to a key within the configuration data.
   *
   * @return bool
   *   TRUE if the $key is overridden. FALSE otherwise.
   */
  public function isOverridden($key) {
    return $this->getOverride($key) !== NULL;
  }

  /**
   * Gets all data from this configuration object.
   *
   * This call provides API symmetry with Config::setData().
   *
   * @return array
   *   All of the data from this config object.
   *
   * @see Config::get()
   *
   * @since 1.23.0 Method added.
   */
  public function getData() {
    return $this->get();
  }

  /**
   * Gets data from this configuration object.
   *
   * @param string $key
   *   A string that maps to a key within the configuration data.
   *   For instance in the following configuration 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.
   *
   * @return mixed
   *   The data that was requested.
   */
  public function get($key = '') {
    $value = $this->getOverride($key);
    if (!isset($value)) {
      $value = $this->getOriginal($key);
    }
    return $value;
  }

  /**
   * Gets the current config value as specified in the written config storage.
   *
   * In most cases, Config::get() should be used to pull the config value and
   * also include any overrides to apply. This method should be used only when
   * explicitly wanting the currently saved value (as stored in a config file)
   * rather than what may be specified in an override (as provided in
   * settings.php).
   *
   * @param string $key
   *   The string that maps to a key with the configuration data. See
   *   Config::get() for full examples.
   *
   * @return mixed
   *   The data that was requested.
   *
   * @see Config::get()
   */
  public function getOriginal($key = '') {
    if (!$this->isLoaded) {
      $this->load();
    }
    if (empty($key)) {
      return $this->data;
    }
    else {
      $parts = explode('.', $key);
      if (count($parts) == 1) {
        return isset($this->data[$key]) ? $this->data[$key] : NULL;
      }
      else {
        $value = $this->data;
        $key_exists = FALSE;
        foreach ($parts as $part) {
          if (is_array($value) && array_key_exists($part, $value)) {
            $value = $value[$part];
            $key_exists = TRUE;
          }
          else {
            $key_exists = FALSE;
            break;
          }
        }
        return $key_exists ? $value : NULL;
      }
    }
  }

  /**
   * Checks if a config value has an override specified.
   *
   * @param string $key
   *   The string that maps to a key with the configuration data.
   *
   *   A key may be overridden at any level, for example if
   *   $key === 'foo.bar.key1', the matched value could be provided by an
   *   override from 'foo.bar.key1', 'foo.bar', or 'foo'. In settings.php any of
   *   the following would provide an overridden value for 'foo.bar.key1':
   *
   *   @code
   *   // Exact match.
   *   $config['example.settings']['foo.bar.key1'] = 'value1';
   *
   *   // One level up.
   *   $config['example.settings']['foo.bar'] = array(
   *     'key1' => 'value1',
   *   );
   *
   *   // A root level override.
   *   $config['example.settings']['foo'] = array(
   *     'bar' => array(
   *       'key1' => 'value1',
   *       'key2' => 'value2',
   *     ),
   *     'baz' => 'other value',
   *   );
   *   @endcode
   *
   * @see Config::get()
   * @see settings.php
   */
  public function getOverride($key) {
    $value = NULL;
    $parts = explode('.', (string) $key);
    $popped_parts = array();
    while ($parts) {
      $assembled_key = implode('.', $parts);
      if (isset($this->overrides[$assembled_key])) {
        // An override is matched at some level.
        $value = $this->overrides[$assembled_key];
        // Drill down back into the override value to get the requested key.
        foreach ($popped_parts as $popped_part) {
          if (isset($value[$popped_part])) {
            $value = $value[$popped_part];
          }
          else {
            $value = NULL;
            $popped_parts = array();
          }
        }
      }
      // If an override was not found at this key, go up a level in the key
      // and continue until there are no more $parts left.
      array_unshift($popped_parts, array_pop($parts));
    }

    return $value;
  }

  /**
   * Gets translated data from this configuration object.
   *
   * @param string $key
   *   A string that maps to a key within the configuration data.
   *   For instance in the following configuration 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 an empty string is returned.
   *   If the key is not 'translatable' key then the original string is returned.
   *   If the key's value is not a string then an empty string is returned.
   *
   * @param array $args
   *   An associative array of replacements to make. Replacements are made in
   *   the same way as the t() function.
   * @param array $options
   *   An associative array of additional options, with the following elements:
   *   - 'langcode' (defaults to the current language): The language code to
   *     translate to a language other than what is used to display the page.
   *   - 'context' (defaults to the empty context): The context the source string
   *     belongs to.
   *
   * @return string|NULL
   *   The translated data that was requested.
   *
   * @see t()
   * @see get()
   */
  public function getTranslated($key = '', $args = array(), $options = array()) {
    if (empty($key)) {
      return NULL;
    }
    $value = $this->get($key);
    if (!is_string($value)) {
      return NULL;
    }
    if (!is_array($this->get('_config_translatables'))) {
      return $value;
    }
    // Ensure that it's a translatable key.
    if (!in_array($key, $this->get('_config_translatables'))) {
      return $value;
    }
    // Set a default context so we can differentiate between config strings.
    // Rather than by using isset() or empty(), checking by key existence
    // allows a NULL context to be used.
    if (!array_key_exists('context', $options)) {
      $options['context'] = 'config:' . $this->getName() . ':' . $key;
    }
    return t($value, $args, $options);
  }

  /**
   * Replaces the data of this configuration object.
   *
   * @param array $data
   *   The new configuration data.
   *
   * @return 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 Config
   *   The configuration object.
   */
  protected function replaceData(array $data) {
    $this->data = $data;
    $this->validated = FALSE;
    return $this;
  }

  /**
   * Sets a value in this configuration object.
   *
   * Note that this will save a NULL value. If wanting to unset a key from the
   * configuration, use Config::clear($key).
   *
   * @param string $key
   *   Identifier to store value in configuration.
   * @param mixed $value
   *   Value to associate with identifier.
   * @param bool $include_overridden_value
   *   Set to TRUE to write the config value even if this key has been
   *   overridden (usually through settings.php). Overridden keys are ignored
   *   by default to prevent accidentally writing values that may be
   *   environment-specific or contain sensitive information that should not
   *   be written to config.
   *
   * @return Config
   *   The configuration object.
   */
  public function set($key, $value, $include_overridden_value = FALSE) {
    // If setting a value that matches an override-provided one, don't actually
    // write it to config.
    $override_value = $this->getOverride($key);
    if (isset($override_value) && ($override_value === $value) && !$include_overridden_value) {
      return $this;
    }

    if (!$this->isLoaded) {
      $this->load();
    }

    // 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 {
      $data = &$this->data;
      $last_key = array_pop($parts);
      foreach ($parts as $part) {
        if (!isset($data)) {
          $data[$part] = array();
        }
        $data = &$data[$part];
      }
      $data[$last_key] = $value;
    }
    $this->validated = FALSE;

    return $this;
  }

  /**
   * Sets multiple values in this configuration object.
   *
   * @param array $options
   *   A keyed array of identifiers mapping to the associated values.
   *
   * @return Config
   *   The configuration object.
   */
  public function setMultiple($options) {
    foreach ($options as $key => $value) {
      $this->set($key, $value);
    }
    return $this;
  }

  /**
   * Sets overrides for this configuration object.
   *
   * @param array $overrides
   *   A list of overrides keyed by strings.
   *
   * @see Config::getOverride()
   */
  public function setOverrides(array $overrides) {
    $this->overrides = $overrides;
  }

  /**
   * Unsets a value in this configuration object.
   *
   * @param string $key
   *   Name of the key whose value should be unset.
   *
   * @return 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 {
      $data = &$this->data;
      $last_key = array_pop($parts);
      foreach ($parts as $part) {
        $data = &$data[$part];
      }
      unset($data[$last_key]);
    }
    $this->validated = FALSE;
    return $this;
  }

  /**
   * Loads configuration data into this object.
   *
   * @return 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->isLoaded = TRUE;
    return $this;
  }

  /**
   * Saves the configuration object.
   *
   * @return Config
   *   The configuration object.
   */
  public function save() {
    // Validate the configuration object name before saving.
    static::validateName($this->name);
    if (!$this->isLoaded) {
      $this->load();
    }
    // Ensure config name is saved in the result.
    $this->data = array_merge(array('_config_name' => $this->name), $this->data);
    $this->storage->write($this->name, $this->data);
    $this->isNew = FALSE;

    // Empty static caches of this config file.
    if ($static = & backdrop_static('config')) {
      foreach ($static as $type => $configs) {
        if (array_key_exists($this->name, $configs)) {
          unset($static[$type][$this->name]);
        }
      }
    }

    return $this;
  }

  /**
   * Deletes the configuration object.
   *
   * @return Config
   *   The configuration object.
   */
  public function delete() {
    $this->data = array();
    $this->storage->delete($this->name);
    $this->isNew = TRUE;
    return $this;
  }

  /**
   * Retrieves the storage used to load and save this configuration object.
   *
   * @return ConfigStorageInterface
   *   The configuration storage object.
   */
  public function getStorage() {
    return $this->storage;
  }
}