CKEditor5PluginManager.php

<?php

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

use Drupal\ckeditor5\Attribute\CKEditor5Plugin;
use Drupal\ckeditor5\HTMLRestrictions;
use Drupal\Component\Assertion\Inspector;
use Drupal\Component\Plugin\Discovery\AttributeBridgeDecorator;
use Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException;
use Drupal\Component\Utility\NestedArray;
use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Plugin\DefaultPluginManager;
use Drupal\Core\Plugin\Discovery\AttributeDiscoveryWithAnnotations;
use Drupal\Core\Plugin\Discovery\ContainerDerivativeDiscoveryDecorator;
use Drupal\Core\Plugin\Discovery\YamlDiscoveryDecorator;
use Drupal\editor\EditorInterface;
use Drupal\filter\FilterPluginCollection;

/**
 * Provides a CKEditor 5 plugin manager.
 *
 * @see \Drupal\ckeditor5\Plugin\CKEditor5PluginInterface
 * @see \Drupal\ckeditor5\Plugin\CKEditor5PluginBase
 * @see \Drupal\ckeditor5\Annotation\CKEditor5Plugin
 * @see plugin_api
 *
 * @internal
 *   CKEditor 5 is currently experimental and should only be leveraged by
 *   experimental modules and development releases of contributed modules.
 *   See https://www.drupal.org/core/experimental for more information.
 */
class CKEditor5PluginManager extends DefaultPluginManager implements CKEditor5PluginManagerInterface {
    
    /**
     * Constructs a CKEditor5PluginManager object.
     *
     * @param \Traversable $namespaces
     *   An object that implements \Traversable which contains the root paths
     *   keyed by the corresponding namespace to look for plugin implementations.
     * @param \Drupal\Core\Cache\CacheBackendInterface $cache_backend
     *   Cache backend instance to use.
     * @param \Drupal\Core\Extension\ModuleHandlerInterface $module_handler
     *   The module handler to invoke the alter hook with.
     */
    public function __construct(\Traversable $namespaces, CacheBackendInterface $cache_backend, ModuleHandlerInterface $module_handler) {
        parent::__construct('Plugin/CKEditor5Plugin', $namespaces, $module_handler, CKEditor5PluginInterface::class, CKEditor5Plugin::class, '\\Drupal\\ckeditor5\\Annotation\\CKEditor5Plugin');
        $this->alterInfo('ckeditor5_plugin_info');
        $this->setCacheBackend($cache_backend, 'ckeditor5_plugins');
    }
    
    /**
     * {@inheritdoc}
     */
    protected function getDiscovery() {
        if (!$this->discovery) {
            $discovery = new AttributeDiscoveryWithAnnotations($this->subdir, $this->namespaces, $this->pluginDefinitionAttributeName, $this->pluginDefinitionAnnotationName, $this->additionalAnnotationNamespaces);
            $discovery = new YamlDiscoveryDecorator($discovery, 'ckeditor5', $this->moduleHandler
                ->getModuleDirectories());
            // Note: adding translatable properties here is impossible because it only
            // supports top-level properties.
            // @see \Drupal\ckeditor5\Plugin\CKEditor5PluginDefinition::label()
            $discovery = new AttributeBridgeDecorator($discovery, $this->pluginDefinitionAttributeName);
            $discovery = new ContainerDerivativeDiscoveryDecorator($discovery);
            $this->discovery = $discovery;
        }
        return $this->discovery;
    }
    
    /**
     * {@inheritdoc}
     */
    public function processDefinition(&$definition, $plugin_id) {
        if (!$definition instanceof CKEditor5PluginDefinition) {
            throw new InvalidPluginDefinitionException($plugin_id, sprintf('The "%s" CKEditor 5 plugin definition must extend %s', $plugin_id, CKEditor5PluginDefinition::class));
        }
        // A derived plugin will still have the ID of the derivative, rather than
        // that of the derived plugin ID (`<base plugin ID>:<derivative ID>`).
        // Generate an updated CKEditor5PluginDefinition.
        // @see \Drupal\Component\Plugin\Discovery\DerivativeDiscoveryDecorator::encodePluginId()
        // @todo Remove this in https://www.drupal.org/project/drupal/issues/2458769.
        $is_derived = $definition->id() !== $plugin_id;
        if ($is_derived) {
            $definition = new CKEditor5PluginDefinition([
                'id' => $plugin_id,
            ] + $definition->toArray());
        }
        $expected_prefix = sprintf("%s_", $definition->getProvider());
        $id = $definition->id();
        if (!str_starts_with($id, $expected_prefix)) {
            throw new InvalidPluginDefinitionException($id, sprintf('The "%s" CKEditor 5 plugin definition must have a plugin ID that starts with "%s".', $id, $expected_prefix));
        }
        try {
            $definition->validateCKEditor5Aspects($id, $definition->toArray());
            $definition->validateDrupalAspects($id, $definition->toArray());
        } catch (InvalidPluginDefinitionException $e) {
            // If this exception is thrown for a derived CKEditor 5 plugin definition,
            // it means the deriver did not generate a valid plugin definition.
            // Re-throw the exception, but tweak the language for DX: clarify it is
            // for a derived plugin definition.
            if ($is_derived) {
                throw new InvalidPluginDefinitionException($e->getPluginId(), str_replace('plugin definition', 'derived plugin definition', $e->getMessage()));
            }
            // Otherwise, the exception was appropriate: re-throw it.
            throw $e;
        }
        parent::processDefinition($definition, $plugin_id);
    }
    
    /**
     * {@inheritdoc}
     */
    public function getPlugin(string $plugin_id, ?EditorInterface $editor) : CKEditor5PluginInterface {
        $configuration = $editor ? self::getPluginConfiguration($editor, $plugin_id) : [];
        return $this->createInstance($plugin_id, $configuration);
    }
    
    /**
     * Gets the plugin configuration (if any) from a text editor config entity.
     *
     * @param \Drupal\editor\EditorInterface $editor
     *   A text editor config entity that is using CKEditor 5.
     * @param string $plugin_id
     *   A CKEditor 5 plugin ID.
     *
     * @return array
     *   The CKEditor 5 plugin configuration, if any.
     *
     * @throws \InvalidArgumentException
     *   Thrown when the method is called with any other text editor than CKEditor 5.
     */
    protected static function getPluginConfiguration(EditorInterface $editor, string $plugin_id) : array {
        if ($editor->getEditor() !== 'ckeditor5') {
            throw new \InvalidArgumentException('This method should only be called on text editor config entities using CKEditor 5.');
        }
        return $editor->getSettings()['plugins'][$plugin_id] ?? [];
    }
    
    /**
     * {@inheritdoc}
     */
    public function getToolbarItems() : array {
        return $this->mergeDefinitionValues('getToolbarItems', $this->getDefinitions());
    }
    
    /**
     * {@inheritdoc}
     */
    public function getAdminLibraries() : array {
        $list = $this->mergeDefinitionValues('getAdminLibrary', $this->getDefinitions());
        // Include main admin library.
        array_unshift($list, 'ckeditor5/internal.admin');
        return $list;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getEnabledLibraries(EditorInterface $editor) : array {
        $list = $this->mergeDefinitionValues('getLibrary', $this->getEnabledDefinitions($editor));
        $list = array_unique($list);
        // Include main library.
        array_unshift($list, 'ckeditor5/internal.drupal.ckeditor5');
        sort($list);
        return $list;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getEnabledDefinitions(EditorInterface $editor) : array {
        $definitions = $this->getDefinitions();
        ksort($definitions);
        $definitions_with_plugins_condition = [];
        foreach ($definitions as $plugin_id => $definition) {
            // Remove definition when plugin has conditions and they are not met.
            if ($definition->hasConditions()) {
                $plugin = $this->getPlugin($plugin_id, $editor);
                if ($this->isPluginDisabled($plugin, $editor)) {
                    unset($definitions[$plugin_id]);
                }
                else {
                    // The `plugins` condition can only be evaluated at the end of
                    // gathering enabled definitions. ::isPluginDisabled() did not yet
                    // evaluate that condition.
                    if (array_key_exists('plugins', $definition->getConditions())) {
                        $definitions_with_plugins_condition[$plugin_id] = $definition;
                    }
                }
            }
            elseif ($definition->hasToolbarItems()) {
                if (empty(array_intersect($editor->getSettings()['toolbar']['items'], array_keys($definition->getToolbarItems())))) {
                    unset($definitions[$plugin_id]);
                }
            }
        }
        // Only enable the arbitrary HTML Support plugin on text formats with no
        // HTML restrictions.
        // @see https://ckeditor.com/docs/ckeditor5/latest/api/html-support.html
        // @see https://github.com/ckeditor/ckeditor5/issues/9856
        if ($editor->getFilterFormat()
            ->getHtmlRestrictions() !== FALSE) {
            unset($definitions['ckeditor5_arbitraryHtmlSupport']);
        }
        // Evaluate `plugins` condition.
        foreach ($definitions_with_plugins_condition as $plugin_id => $definition) {
            if (!empty(array_diff($definition->getConditions()['plugins'], array_keys($definitions)))) {
                unset($definitions[$plugin_id]);
            }
        }
        if (!isset($definitions['ckeditor5_arbitraryHtmlSupport'])) {
            $restrictions = new HTMLRestrictions($this->getProvidedElements(array_keys($definitions), $editor, FALSE));
            if ($restrictions->getWildcardSubset()
                ->allowsNothing()) {
                // This is only reached if arbitrary HTML is not enabled. If wildcard
                // tags (such as $text-container) are present, they need to
                // be resolved via the wildcardHtmlSupport plugin.
                // @see \Drupal\ckeditor5\Plugin\CKEditor5PluginManager::getCKEditor5PluginConfig()
                unset($definitions['ckeditor5_wildcardHtmlSupport']);
            }
        }
        else {
            unset($definitions['ckeditor5_wildcardHtmlSupport']);
        }
        return $definitions;
    }
    
    /**
     * {@inheritdoc}
     */
    public function findPluginSupportingElement(string $tag) : ?string {
        // This will contain the element config for a plugin found to support $tag,
        // so it can be compared to additional plugins that support $tag so the
        // plugin with the most permissive config can be the id returned.
        $selected_provided_elements = [];
        $plugin_id = NULL;
        foreach ($this->getDefinitions() as $id => $definition) {
            $provided_elements = $this->getProvidedElements([
                $id,
            ]);
            // Multiple plugins may support the $tag being searched for.
            if (array_key_exists($tag, $provided_elements)) {
                // Skip plugins with conditions as those plugins can't be guaranteed to
                // provide a given tag without additional criteria being met. In the
                // future we could possibly add support for automatically enabling
                // filters or other similar requirements a plugin might need in order to
                // be enabled and provide the tag it supports. For now, we assume such
                // configuration cannot be modified programmatically.
                if ($definition->hasConditions()) {
                    continue;
                }
                // True if a plugin has already been selected. If another plugin
                // supports $tag, it will be compared against this one. Whichever
                // provides broader support for $tag will be the plugin id returned by
                // this method.
                $selected_plugin = isset($selected_provided_elements[$tag]);
                $selected_config = $selected_provided_elements[$tag] ?? FALSE;
                // True if a plugin supporting $tag has been selected but does not allow
                // any attributes while the plugin currently being checked does support
                // attributes.
                $adds_attribute_config = is_array($provided_elements[$tag]) && $selected_plugin && !is_array($selected_config);
                $broader_attribute_config = FALSE;
                // If the selected plugin and the plugin being checked both have arrays
                // for $tag configuration, they both have attribute configuration. Check
                // which attribute configuration is more permissive.
                if ($selected_plugin && is_array($selected_config) && is_array($provided_elements[$tag])) {
                    $selected_plugin_full_attributes = array_filter($selected_config, function ($attribute_config) {
                        return !is_array($attribute_config);
                    });
                    $being_checked_plugin_full_attributes = array_filter($provided_elements[$tag], function ($attribute_config) {
                        return !is_array($attribute_config);
                    });
                    if (count($being_checked_plugin_full_attributes) > count($selected_plugin_full_attributes)) {
                        $broader_attribute_config = TRUE;
                    }
                }
                if (empty($selected_provided_elements) || $broader_attribute_config || $adds_attribute_config) {
                    $selected_provided_elements = $provided_elements;
                    $plugin_id = $id;
                }
            }
        }
        return $plugin_id;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getCKEditor5PluginConfig(EditorInterface $editor) : array {
        $definitions = $this->getEnabledDefinitions($editor);
        // Allow plugin to modify config, such as loading dynamic values.
        $config = [];
        foreach ($definitions as $plugin_id => $definition) {
            $plugin = $this->getPlugin($plugin_id, $editor);
            $config[$plugin_id] = $plugin->getDynamicPluginConfig($definition->getCKEditor5Config(), $editor);
        }
        // CKEditor 5 interprets wildcards from a "CKEditor 5 model element"
        // perspective, Drupal interprets wildcards from a "HTML element"
        // perspective. GHS is used to reconcile those two perspectives, to ensure
        // all expected HTML elements truly are supported.
        // The `ckeditor5_wildcardHtmlSupport` is automatically enabled when
        // necessary, and only when necessary.
        // @see \Drupal\ckeditor5\Plugin\CKEditor5PluginManager::getEnabledDefinitions()
        if (isset($definitions['ckeditor5_wildcardHtmlSupport'])) {
            $allowed_elements = new HTMLRestrictions($this->getProvidedElements(array_keys($definitions), $editor, FALSE));
            // Compute the net new elements that the wildcard tags resolve into.
            $concrete_allowed_elements = $allowed_elements->getConcreteSubset();
            $net_new_elements = $allowed_elements->diff($concrete_allowed_elements);
            $config['ckeditor5_wildcardHtmlSupport'] = [
                'htmlSupport' => [
                    'allow' => $net_new_elements->toGeneralHtmlSupportConfig(),
                ],
            ];
        }
        return [
            'plugins' => $this->mergeDefinitionValues('getCKEditor5Plugins', $definitions),
            'config' => NestedArray::mergeDeepArray($config),
        ];
    }
    
    /**
     * {@inheritdoc}
     */
    public function getProvidedElements(array $plugin_ids = [], ?EditorInterface $editor = NULL, bool $resolve_wildcards = TRUE, bool $creatable_elements_only = FALSE) : array {
        $plugins = $this->getDefinitions();
        if (!empty($plugin_ids)) {
            $plugins = array_intersect_key($plugins, array_flip($plugin_ids));
        }
        $elements = HTMLRestrictions::emptySet();
        foreach ($plugins as $id => $definition) {
            // Some CKEditor 5 plugins only provide functionality, not additional
            // elements.
            if (!$definition->hasElements()) {
                continue;
            }
            $defined_elements = $definition->getElements();
            if (is_a($definition->getClass(), CKEditor5PluginElementsSubsetInterface::class, TRUE)) {
                // ckeditor5_sourceEditing is the edge case here: it is the only plugin
                // that is allowed to return a superset. It's a special case because it
                // is through configuring this particular plugin that additional HTML
                // tags can be allowed.
                // The list of tags it supports is generated dynamically. In its default
                // configuration it does support any HTML tags.
                if ($id === 'ckeditor5_sourceEditing') {
                    $defined_elements = !isset($editor) ? [] : $this->getPlugin($id, $editor)
                        ->getElementsSubset();
                }
                elseif (isset($editor)) {
                    $subset = $this->getPlugin($id, $editor)
                        ->getElementsSubset();
                    $subset_restrictions = HTMLRestrictions::fromString(implode($subset));
                    $defined_restrictions = HTMLRestrictions::fromString(implode($defined_elements));
                    // Determine max supported elements by resolving wildcards in the
                    // restrictions defined by the plugin.
                    $max_supported = $defined_restrictions;
                    if (!$defined_restrictions->getWildcardSubset()
                        ->allowsNothing()) {
                        $concrete_tags_to_use_to_resolve_wildcards = $subset_restrictions->extractPlainTagsSubset();
                        $max_supported = $max_supported->merge($concrete_tags_to_use_to_resolve_wildcards)
                            ->diff($concrete_tags_to_use_to_resolve_wildcards);
                    }
                    $not_in_max_supported = $subset_restrictions->diff($max_supported);
                    if (!$not_in_max_supported->allowsNothing()) {
                        // If the editor is still being configured, the configuration may
                        // not yet be valid.
                        if ($editor->isNew()) {
                            $subset = [];
                        }
                        else {
                            throw new \LogicException(sprintf('The "%s" CKEditor 5 plugin implements ::getElementsSubset() and did not return a subset, the following tags are absent from the plugin definition: "%s".', $id, implode(' ', $not_in_max_supported->toCKEditor5ElementsArray())));
                        }
                    }
                    // Also detect what is technically a valid subset, but has lost the
                    // ability to create tags that are still in the subset. This points to
                    // a bug in the plugin's ::getElementsSubset() logic.
                    $defined_creatable = HTMLRestrictions::fromString(implode($definition->getCreatableElements()));
                    $subset_creatable_actual = HTMLRestrictions::fromString(implode(array_filter($subset, [
                        CKEditor5PluginDefinition::class,
                        'isCreatableElement',
                    ])));
                    $subset_creatable_needed = $subset_restrictions->extractPlainTagsSubset()
                        ->intersect($defined_creatable);
                    $missing_creatable_for_subset = $subset_creatable_needed->diff($subset_creatable_actual);
                    if (!$missing_creatable_for_subset->allowsNothing()) {
                        throw new \LogicException(sprintf('The "%s" CKEditor 5 plugin implements ::getElementsSubset() and did return a subset ("%s") but the following tags can no longer be created: "%s".', $id, implode($subset_restrictions->toCKEditor5ElementsArray()), implode($missing_creatable_for_subset->toCKEditor5ElementsArray())));
                    }
                    $defined_elements = $subset;
                }
            }
            assert(Inspector::assertAllStrings($defined_elements));
            if ($creatable_elements_only) {
                // @see \Drupal\ckeditor5\Plugin\CKEditor5PluginDefinition::getCreatableElements()
                $defined_elements = array_filter($defined_elements, [
                    CKEditor5PluginDefinition::class,
                    'isCreatableElement',
                ]);
            }
            foreach ($defined_elements as $element) {
                $additional_elements = HTMLRestrictions::fromString($element);
                $elements = $elements->merge($additional_elements);
            }
        }
        return $elements->getAllowedElements($resolve_wildcards);
    }
    
    /**
     * Returns array of merged values for the given plugin definitions.
     *
     * @param string $get_method
     *   Which CKEditor5PluginDefinition getter to call to get values to merge.
     * @param \Drupal\ckeditor5\Plugin\CKEditor5PluginDefinition[] $definitions
     *   The plugin definitions whose values to merge.
     *
     * @return array
     *   List of merged values for the given plugin definition method.
     */
    protected function mergeDefinitionValues(string $get_method, array $definitions) : array {
        assert(method_exists(CKEditor5PluginDefinition::class, $get_method));
        $has_method = 'has' . substr($get_method, 3);
        assert(method_exists(CKEditor5PluginDefinition::class, $has_method));
        $per_plugin = array_filter(array_map(function (CKEditor5PluginDefinition $definition) use ($get_method, $has_method) {
            if ($definition->{$has_method}()) {
                return $definition->{$get_method}();
            }
        }, $definitions));
        return array_reduce($per_plugin, function (array $result, $current) : array {
            return is_array($current) && is_array(reset($current)) ? $result + $current : array_merge($result, (array) $current);
        }, []);
    }
    
    /**
     * Checks whether a plugin must be disabled due to unmet conditions.
     *
     * @param \Drupal\ckeditor5\Plugin\CKEditor5PluginInterface $plugin
     *   A CKEditor 5 plugin instance.
     * @param \Drupal\editor\EditorInterface $editor
     *   A configured text editor object.
     *
     * @return bool
     *   Whether the plugin is disabled due to unmet conditions.
     */
    protected function isPluginDisabled(CKEditor5PluginInterface $plugin, EditorInterface $editor) : bool {
        assert($plugin->getPluginDefinition()
            ->hasConditions());
        foreach ($plugin->getPluginDefinition()
            ->getConditions() as $condition_type => $required_value) {
            switch ($condition_type) {
                case 'toolbarItem':
                    if (!in_array($required_value, $editor->getSettings()['toolbar']['items'])) {
                        return TRUE;
                    }
                    break;
                case 'imageUploadStatus':
                    $image_upload_status = $editor->getImageUploadSettings()['status'] ?? FALSE;
                    return $image_upload_status !== $required_value;
                case 'filter':
                    $filters = $editor->getFilterFormat()
                        ->filters();
                    assert($filters instanceof FilterPluginCollection);
                    if (!$filters->has($required_value) || !$filters->get($required_value)->status) {
                        return TRUE;
                    }
                    break;
                case 'requiresConfiguration':
                    $intersection = array_intersect($plugin->getConfiguration(), $required_value);
                    return $intersection !== $required_value;
                case 'plugins':
                    // Tricky: this cannot yet be evaluated here. It will evaluated later.
                    // @see \Drupal\ckeditor5\Plugin\CKEditor5PluginManager::getEnabledDefinitions()
                    return FALSE;
            }
        }
        return FALSE;
    }

}