ConfigurableTrait.php

<?php

declare (strict_types=1);
namespace Drupal\Core\Plugin;

use Drupal\Component\Utility\NestedArray;

/**
 * Implementation class for \Drupal\Component\Plugin\ConfigurableInterface.
 *
 * In order for configurable plugins to maintain their configuration, the
 * default configuration must be merged into any explicitly defined
 * configuration. This trait provides the appropriate getters and setters to
 * handle this logic, removing the need for excess boilerplate.
 *
 * To use this trait implement ConfigurableInterface and add a constructor. In
 * the constructor call the parent constructor and then call setConfiguration().
 * That will merge the explicitly defined plugin configuration and the default
 * plugin configuration.
 *
 * @ingroup Plugin
 */
trait ConfigurableTrait {
    
    /**
     * Configuration information passed into the plugin.
     *
     * This property is declared in \Drupal\Component\Plugin\PluginBase as well,
     * which most classes using this trait will ultimately be extending. It is
     * re-declared here to make the trait self-contained and to permit use of the
     * trait in classes that do not extend PluginBase.
     *
     * @var array
     */
    protected $configuration;
    
    /**
     * Gets this plugin's configuration.
     *
     * @return array
     *   An associative array containing the plugin's configuration.
     *
     * @see \Drupal\Component\Plugin\ConfigurableInterface::getConfiguration()
     */
    public function getConfiguration() {
        return $this->configuration;
    }
    
    /**
     * Sets the configuration for this plugin instance.
     *
     * The provided configuration is merged with the plugin's default
     * configuration. If the same configuration key exists in both configurations,
     * then the value in the provided configuration will override the default.
     *
     * @param array $configuration
     *   An associative array containing the plugin's configuration.
     *
     * @return $this
     *
     * @see \Drupal\Component\Plugin\ConfigurableInterface::setConfiguration()
     */
    public function setConfiguration(array $configuration) {
        $this->configuration = NestedArray::mergeDeepArray([
            $this->defaultConfiguration(),
            $configuration,
        ], TRUE);
        return $this;
    }
    
    /**
     * Gets default configuration for this plugin.
     *
     * @return array
     *   An associative array containing the default configuration.
     *
     * @see \Drupal\Component\Plugin\ConfigurableInterface::defaultConfiguration()
     */
    public function defaultConfiguration() {
        return [];
    }

}