SelectionPluginBase.php

<?php

namespace Drupal\Core\Entity\EntityReferenceSelection;

use Drupal\Component\Plugin\ConfigurableInterface;
use Drupal\Component\Plugin\ConfigurablePluginInterface;
use Drupal\Component\Plugin\DependentPluginInterface;
use Drupal\Component\Utility\NestedArray;
use Drupal\Core\Database\Query\SelectInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Plugin\PluginBase;

/**
 * Provides a base class for configurable selection handlers.
 */
abstract class SelectionPluginBase extends PluginBase implements SelectionInterface, ConfigurableInterface, DependentPluginInterface, ConfigurablePluginInterface {
    
    /**
     * Constructs a new selection object.
     *
     * @param array $configuration
     *   A configuration array containing information about the plugin instance.
     * @param string $plugin_id
     *   The plugin_id for the plugin instance.
     * @param mixed $plugin_definition
     *   The plugin implementation definition.
     */
    public function __construct(array $configuration, $plugin_id, $plugin_definition) {
        parent::__construct($configuration, $plugin_id, $plugin_definition);
        $this->setConfiguration($configuration);
    }
    
    /**
     * {@inheritdoc}
     */
    public function defaultConfiguration() {
        return [
            'target_type' => NULL,
            // @todo Remove this key in Drupal 9.0.x.
'handler' => $this->getPluginId(),
            'entity' => NULL,
        ];
    }
    
    /**
     * {@inheritdoc}
     */
    public function getConfiguration() {
        return $this->configuration;
    }
    
    /**
     * {@inheritdoc}
     */
    public function setConfiguration(array $configuration) {
        // Resolve backward compatibility level configurations, if any.
        $this->resolveBackwardCompatibilityConfiguration($configuration);
        // Merge in defaults.
        $this->configuration = NestedArray::mergeDeep($this->defaultConfiguration(), $configuration);
        // Ensure a backward compatibility level configuration.
        $this->ensureBackwardCompatibilityConfiguration();
    }
    
    /**
     * {@inheritdoc}
     */
    public function calculateDependencies() {
        return [];
    }
    
    /**
     * {@inheritdoc}
     */
    public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
        return $form;
    }
    
    /**
     * {@inheritdoc}
     */
    public function validateConfigurationForm(array &$form, FormStateInterface $form_state) {
    }
    
    /**
     * {@inheritdoc}
     */
    public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {
    }
    
    /**
     * {@inheritdoc}
     */
    public function entityQueryAlter(SelectInterface $query) {
    }
    
    /**
     * Moves the backward compatibility level configurations in the right place.
     *
     * In order to keep backward compatibility, we copy all settings, except
     * 'target_type', 'handler' and 'entity' under 'handler_settings', following
     * the structure from the field config. If the plugin was instantiated using
     * the 'handler_settings' level, those values will be used. In case of
     * conflict, the root level settings will take precedence. The backward
     * compatibility aware configuration will have the next structure:
     * - target_type
     * - handler (will be removed in Drupal 9.0.x, it's the plugin id)
     * - entity
     * - setting_1
     * - setting_2
     *   ...
     * - setting_N
     * - handler_settings: (will be removed in Drupal 9.0.x)
     *   - setting_1
     *   - setting_2
     *     ...
     *   - setting_N
     *
     * @param array $configuration
     *   The configuration array to be altered.
     *
     * @internal
     *
     * @todo Remove this method call and its method in Drupal 9.
     *
     * @see https://www.drupal.org/project/drupal/issues/3069757
     * @see https://www.drupal.org/node/2870971
     */
    protected function resolveBackwardCompatibilityConfiguration(array &$configuration) {
        if (isset($this->defaultConfiguration()['handler_settings'])) {
            throw new \InvalidArgumentException("{$this->getPluginDefinition()['class']}::defaultConfiguration() should not contain a 'handler_settings' key. All settings should be placed in the root level.");
        }
        // Extract the BC level from the passed configuration, if any.
        if (array_key_exists('handler_settings', $configuration)) {
            if (!is_array($configuration['handler_settings'])) {
                throw new \InvalidArgumentException("The setting 'handler_settings' is reserved and cannot be used.");
            }
            @trigger_error("Providing settings under 'handler_settings' is deprecated in drupal:8.4.0 support for 'handler_settings' is removed from drupal:9.0.0. Move the settings in the root of the configuration array. See https://www.drupal.org/node/2870971", E_USER_DEPRECATED);
            // Settings passed in the root level take precedence over BC settings.
            $configuration += $configuration['handler_settings'];
            unset($configuration['handler_settings']);
        }
    }
    
    /**
     * Ensures a backward compatibility level configuration.
     *
     * @internal
     *
     * @todo Remove this method call and its method in Drupal 9.
     *
     * @see https://www.drupal.org/project/drupal/issues/3069757
     * @see https://www.drupal.org/node/2870971
     */
    protected function ensureBackwardCompatibilityConfiguration() {
        $keys = [
            'handler',
            'target_type',
            'entity',
            'handler_settings',
        ];
        // Synchronize back 'handler_settings'.
        foreach ($this->configuration as $key => $value) {
            // Filter out keys that belong strictly to the root level.
            if (!in_array($key, $keys, TRUE)) {
                $this->configuration['handler_settings'][$key] = $value;
            }
        }
    }

}