Issue #2216961 by Gábor Hojtsy, xjm | alexpott: Document Config, ConfigBase,...

Issue #2216961 by Gábor Hojtsy, xjm | alexpott: Document Config, ConfigBase, and StorableConfigBase.

core/lib/Drupal/Core/Config/Config.php

@@ -18,8 +18,14 @@
 
 /**
  * Defines the default configuration object.
+ *
+ * Encapsulates all capabilities needed for configuration handling for a
+ * specific configuration object, including support for runtime overrides. The
+ * overrides are handled on top of the stored configuration so they are not
+ * saved back to storage.
  */
 class Config extends StorableConfigBase {
+
   /**
    * An event dispatcher instance to use for configuration events.
    *
@@ -276,111 +282,6 @@ public function delete() {
     return $this;
   }
 
-  /**
-   * Retrieves 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;
-  }
-
-  /**
-   * 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) {
-    // Preserve integer keys so that configuration keys are not changed.
-    $this->setData(NestedArray::mergeDeepArray(array($this->data, $data_to_merge), TRUE));
-    return $this;
-  }
-
-  /**
-   * Gets the schema wrapper for the whole configuration object.
-   *
-   * The schema wrapper is dependent on the configuration name and the whole
-   * data structure, so if the name or the data changes in any way, the wrapper
-   * should be reset.
-   *
-   * @return \Drupal\Core\Config\Schema\Element
-   */
-  protected function getSchemaWrapper() {
-    if (!isset($this->schemaWrapper)) {
-      $definition = $this->typedConfigManager->getDefinition($this->name);
-      $this->schemaWrapper = $this->typedConfigManager->create($definition, $this->data);
-    }
-    return $this->schemaWrapper;
-  }
-
-  /**
-   * Casts the value to correct data type using the configuration schema.
-   *
-   * @param string $key
-   *   A string that maps to a key within the configuration data.
-   * @param string $value
-   *   Value to associate with the key.
-   *
-   * @return mixed
-   *   The value cast to the type indicated in the schema.
-   *
-   * @throws \Drupal\Core\Config\UnsupportedDataTypeConfigException
-   *   Exception on unsupported/undefined data type deducted.
-   */
-  protected function castValue($key, $value) {
-    if ($value === NULL) {
-      $value = NULL;
-    }
-    elseif (is_scalar($value)) {
-      try {
-        $element = $this->getSchemaWrapper()->get($key);
-        if ($element instanceof PrimitiveInterface) {
-          // Special handling for integers and floats since the configuration
-          // system is primarily concerned with saving values from the Form API
-          // we have to special case the meaning of an empty string for numeric
-          // types. In PHP this would be casted to a 0 but for the purposes of
-          // configuration we need to treat this as a NULL.
-          if ($value === '' && ($element instanceof IntegerInterface || $element instanceof FloatInterface)) {
-            $value = NULL;
-          }
-          else {
-            $value = $element->getCastedValue();
-          }
-        }
-        else {
-          // Config only supports primitive data types. If the config schema
-          // does define a type $element will be an instance of
-          // \Drupal\Core\Config\Schema\Property. Convert it to string since it
-          // is the safest possible type.
-          $value = $element->getString();
-        }
-      }
-      catch (SchemaIncompleteException $e) {
-        // @todo throw an exception due to an incomplete schema.
-        // Fix as part of https://drupal.org/node/2183983.
-      }
-    }
-    else {
-      // Throw exception on any non-scalar or non-array value.
-      if (!is_array($value)) {
-        throw new UnsupportedDataTypeConfigException(String::format('Invalid data type for config element @name:@key', array(
-          '@name' => $this->getName(),
-          '@key' => $key,
-        )));
-      }
-      // Recurse into any nested keys.
-      foreach ($value as $nested_value_key => $nested_value) {
-        $value[$nested_value_key] = $this->castValue($key . '.' . $nested_value_key, $nested_value);
-      }
-    }
-    return $value;
-  }
-
   /**
    * Returns the language object for this Config object.
    *

core/lib/Drupal/Core/Config/ConfigBase.php

@@ -11,6 +11,21 @@
 use Drupal\Component\Utility\String;
 use \Drupal\Core\DependencyInjection\DependencySerialization;
 
+/**
+ * Provides a base class for configuration objects with get/set support.
+ *
+ * Encapsulates all capabilities needed for runtime configuration handling for
+ * a specific configuration object.
+ *
+ * Extend directly from this class for non-storable configuration where the
+ * configuration API is desired but storage is not possible; for example, if
+ * the data is derived at runtime. For storable configuration, extend
+ * \Drupal\Core\Config\StorableConfigBase.
+ *
+ * @see \Drupal\Core\Config\StorableConfigBase
+ * @see \Drupal\Core\Config\Config
+ * @see \Drupal\Core\Theme\ThemeSettings
+ */
 abstract class ConfigBase extends DependencySerialization {
 
   /**
@@ -204,6 +219,8 @@ public function clear($key) {
    *   The configuration object.
    */
   public function merge(array $data_to_merge) {
-    return $this->setData(NestedArray::mergeDeepArray(array($this->data, $data_to_merge), TRUE));
+    // Preserve integer keys so that configuration keys are not changed.
+    $this->setData(NestedArray::mergeDeepArray(array($this->data, $data_to_merge), TRUE));
+    return $this;
   }
 }

core/lib/Drupal/Core/Config/StorableConfigBase.php

@@ -13,6 +13,18 @@
 use Drupal\Core\TypedData\Type\FloatInterface;
 use Drupal\Core\TypedData\Type\IntegerInterface;
 
+/**
+ * Provides a base class for configuration objects with storage support.
+ *
+ * Encapsulates all capabilities needed for configuration handling for a
+ * specific configuration object, including storage and data type casting.
+ *
+ * The default implementation in \Drupal\Core\Config\Config adds support for
+ * runtime overrides. Extend from StorableConfigBase directly to manage
+ * configuration with a storage backend that does not support overrides.
+ *
+ * @see \Drupal\Core\Config\Config
+ */
 abstract class StorableConfigBase extends ConfigBase {
 
   /**

core/lib/Drupal/Core/Theme/ThemeSettings.php

@@ -10,7 +10,13 @@
 use Drupal\Core\Config\ConfigBase;
 
 /**
- * Defines the default theme settings object.
+ * Provides a configuration API wrapper for runtime merged theme settings.
+ *
+ * Theme settings use configuration for base values but the runtime theme
+ * settings are calculated based on various site settings and are therefore
+ * not persisted.
+ *
+ * @see theme_get_setting()
  */
 class ThemeSettings extends ConfigBase {