Merge pull request #9769 from cakephp/3.next-getter-setter

Split Config trait modals into getter and setter.

src/Core/InstanceConfigTrait.php

@@ -40,6 +40,85 @@ trait InstanceConfigTrait
     protected $_configInitialized = false;
 
     /**
+     * Sets the config.
+     *
+     * ### Usage
+     *
+     * Setting a specific value:
+     *
+     * ```
+     * $this->setConfig('key', $value);
+     * ```
+     *
+     * Setting a nested value:
+     *
+     * ```
+     * $this->setConfig('some.nested.key', $value);
+     * ```
+     *
+     * Updating multiple config settings at the same time:
+     *
+     * ```
+     * $this->setConfig(['one' => 'value', 'another' => 'value']);
+     * ```
+     *
+     * @param string|array $key The key to set, or a complete array of configs.
+     * @param mixed|null $value The value to set.
+     * @param bool $merge Whether to recursively merge or overwrite existing config, defaults to true.
+     * @return $this
+     * @throws \Cake\Core\Exception\Exception When trying to set a key that is invalid.
+     */
+    public function setConfig($key, $value = null, $merge = true)
+    {
+        if (!$this->_configInitialized) {
+            $this->_config = $this->_defaultConfig;
+            $this->_configInitialized = true;
+        }
+
+        $this->_configWrite($key, $value, $merge);
+
+        return $this;
+    }
+
+    /**
+     * Returns the config.
+     *
+     * ### Usage
+     *
+     * Reading the whole config:
+     *
+     * ```
+     * $this->getConfig();
+     * ```
+     *
+     * Reading a specific value:
+     *
+     * ```
+     * $this->getConfig('key');
+     * ```
+     *
+     * Reading a nested value:
+     *
+     * ```
+     * $this->getConfig('some.nested.key');
+     * ```
+     *
+     * @param string|null $key The key to get or null for the whole config.
+     * @return mixed Config value being read.
+     */
+    public function getConfig($key = null)
+    {
+        if (!$this->_configInitialized) {
+            $this->_config = $this->_defaultConfig;
+            $this->_configInitialized = true;
+        }
+
+        return $this->_configRead($key);
+    }
+
+    /**
+     * Gets/Sets the config.
+     *
      * ### Usage
      *
      * Reading the whole config:
@@ -78,6 +157,7 @@ trait InstanceConfigTrait
      * $this->config(['one' => 'value', 'another' => 'value']);
      * ```
      *
+     * @deprecated 3.4.0 use setConfig()/getConfig() instead.
      * @param string|array|null $key The key to get/set, or a complete array of configs.
      * @param mixed|null $value The value to set.
      * @param bool $merge Whether to recursively merge or overwrite existing config, defaults to true.
@@ -86,18 +166,11 @@ trait InstanceConfigTrait
      */
     public function config($key = null, $value = null, $merge = true)
     {
-        if (!$this->_configInitialized) {
-            $this->_config = $this->_defaultConfig;
-            $this->_configInitialized = true;
-        }
-
         if (is_array($key) || func_num_args() >= 2) {
-            $this->_configWrite($key, $value, $merge);
-
-            return $this;
+            return $this->setConfig($key, $value, $merge);
         }
 
-        return $this->_configRead($key);
+        return $this->getConfig($key);
     }
 
     /**
@@ -139,7 +212,7 @@ trait InstanceConfigTrait
     }
 
     /**
-     * Read a config variable
+     * Reads a config key.
      *
      * @param string|null $key Key to read.
      * @return mixed
@@ -169,7 +242,7 @@ trait InstanceConfigTrait
     }
 
     /**
-     * Write a config variable
+     * Writes a config key.
      *
      * @param string|array $key Key to write to.
      * @param mixed $value Value to write.
@@ -230,7 +303,7 @@ trait InstanceConfigTrait
     }
 
     /**
-     * Delete a single config key
+     * Deletes a single config key.
      *
      * @param string $key Key to delete.
      * @return void

src/Core/StaticConfigTrait.php

@@ -16,6 +16,7 @@ namespace Cake\Core;
 
 use BadMethodCallException;
 use InvalidArgumentException;
+use LogicException;
 
 /**
  * A trait that provides a set of static methods to manage configuration
@@ -35,8 +36,7 @@ trait StaticConfigTrait
     protected static $_config = [];
 
     /**
-     * This method can be used to define configuration adapters for an application
-     * or read existing configuration.
+     * This method can be used to define configuration adapters for an application.
      *
      * To change an adapter's configuration at runtime, first drop the adapter and then
      * reconfigure it.
@@ -48,50 +48,41 @@ trait StaticConfigTrait
      * Assuming that the class' name is `Cache` the following scenarios
      * are supported:
      *
-     * Reading config data back:
-     *
-     * ```
-     * Cache::config('default');
-     * ```
-     *
      * Setting a cache engine up.
      *
      * ```
-     * Cache::config('default', $settings);
+     * Cache::setConfig('default', $settings);
      * ```
      *
      * Injecting a constructed adapter in:
      *
      * ```
-     * Cache::config('default', $instance);
+     * Cache::setConfig('default', $instance);
      * ```
      *
      * Configure multiple adapters at once:
      *
      * ```
-     * Cache::config($arrayOfConfig);
+     * Cache::setConfig($arrayOfConfig);
      * ```
      *
      * @param string|array $key The name of the configuration, or an array of multiple configs.
-     * @param array|null $config An array of name => configuration data for adapter.
-     * @return array|null Null when adding configuration or an array of configuration data when reading.
+     * @param array $config An array of name => configuration data for adapter.
      * @throws \BadMethodCallException When trying to modify an existing config.
+     * @throws \LogicException When trying to store an invalid structured config array.
+     * @return void
      */
-    public static function config($key, $config = null)
+    public static function setConfig($key, $config = null)
     {
         if ($config === null) {
-            // Read config.
-            if (is_string($key)) {
-                return isset(static::$_config[$key]) ? static::$_config[$key] : null;
+            if (!is_array($key)) {
+                throw new LogicException('If config is null, key must be an array.');
             }
-
-            if (is_array($key)) {
-                foreach ($key as $name => $settings) {
-                    static::config($name, $settings);
-                }
-
-                return;
+            foreach ($key as $name => $settings) {
+                static::setConfig($name, $settings);
             }
+
+            return;
         }
 
         if (isset(static::$_config[$key])) {
@@ -116,6 +107,72 @@ trait StaticConfigTrait
     }
 
     /**
+     * Reads existing configuration.
+     *
+     * @param string $key The name of the configuration.
+     * @return array|null Array of configuration data.
+     */
+    public static function getConfig($key)
+    {
+        return isset(static::$_config[$key]) ? static::$_config[$key] : null;
+    }
+
+    /**
+     * This method can be used to define configuration adapters for an application
+     * or read existing configuration.
+     *
+     * To change an adapter's configuration at runtime, first drop the adapter and then
+     * reconfigure it.
+     *
+     * Adapters will not be constructed until the first operation is done.
+     *
+     * ### Usage
+     *
+     * Assuming that the class' name is `Cache` the following scenarios
+     * are supported:
+     *
+     * Reading config data back:
+     *
+     * ```
+     * Cache::config('default');
+     * ```
+     *
+     * Setting a cache engine up.
+     *
+     * ```
+     * Cache::config('default', $settings);
+     * ```
+     *
+     * Injecting a constructed adapter in:
+     *
+     * ```
+     * Cache::config('default', $instance);
+     * ```
+     *
+     * Configure multiple adapters at once:
+     *
+     * ```
+     * Cache::config($arrayOfConfig);
+     * ```
+     *
+     * @deprecated 3.4.0 Use setConfig()/getConfig() instead.
+     * @param string|array $key The name of the configuration, or an array of multiple configs.
+     * @param array|null $config An array of name => configuration data for adapter.
+     * @return array|null Null when adding configuration or an array of configuration data when reading.
+     * @throws \BadMethodCallException When trying to modify an existing config.
+     */
+    public static function config($key, $config = null)
+    {
+        if ($config !== null || !is_string($key)) {
+            static::setConfig($key, $config);
+
+            return null;
+        }
+
+        return static::getConfig($key);
+    }
+
+    /**
      * Drops a constructed adapter.
      *
      * If you wish to modify an existing configuration, you should drop it,
@@ -247,17 +304,39 @@ trait StaticConfigTrait
     }
 
     /**
-     * Returns or updates the DSN class map for this class
+     * Updates the DSN class map for this class.
+     *
+     * @param array $map Additions/edits to the class map to apply.
+     * @return void
+     */
+    public static function setDsnClassMap(array $map)
+    {
+        static::$_dsnClassMap = $map + static::$_dsnClassMap;
+    }
+
+    /**
+     * Returns the DSN class map for this class.
      *
-     * @param array|null $map Additions/edits to the class map to apply
+     * @return array
+     */
+    public static function getDsnClassMap()
+    {
+        return static::$_dsnClassMap;
+    }
+
+    /**
+     * Returns or updates the DSN class map for this class.
+     *
+     * @deprecated 3.4.0 Use setDsnClassMap()/getDsnClassMap() instead.
+     * @param array|null $map Additions/edits to the class map to apply.
      * @return array
      */
     public static function dsnClassMap(array $map = null)
     {
         if ($map !== null) {
-            static::$_dsnClassMap = $map + static::$_dsnClassMap;
+            static::setDsnClassMap($map);
         }
 
-        return static::$_dsnClassMap;
+        return static::getDsnClassMap();
     }
 }