Mapping.php

<?php

namespace Drupal\Core\Config\Schema;

use Drupal\Component\Utility\NestedArray;
use Drupal\Core\TypedData\DataDefinitionInterface;
use Drupal\Core\TypedData\MapDataDefinition;
use Drupal\Core\TypedData\TypedDataInterface;

/**
 * Defines a mapping configuration element.
 *
 * This object may contain any number and type of nested properties and each
 * property key may have its own definition in the 'mapping' property of the
 * configuration schema.
 *
 * Properties in the configuration value that are not defined in the mapping
 * will get the 'undefined' data type.
 *
 * Read https://www.drupal.org/node/1905070 for more details about configuration
 * schema, types and type resolution.
 */
class Mapping extends ArrayElement {
    
    /**
     * {@inheritdoc}
     */
    public function __construct(DataDefinitionInterface $definition, $name = NULL, ?TypedDataInterface $parent = NULL) {
        assert($definition instanceof MapDataDefinition);
        // Validate basic structure.
        foreach ($definition['mapping'] as $key => $key_definition) {
            // Guide developers when a config schema definition is wrong.
            if (!is_array($key_definition)) {
                if (!$parent) {
                    throw new \LogicException(sprintf("The mapping definition at `%s` is invalid: its `%s` key contains a %s. It must be an array.", $name, $key, gettype($key_definition)));
                }
                else {
                    throw new \LogicException(sprintf("The mapping definition at `%s:%s` is invalid: its `%s` key contains a %s. It must be an array.", $parent->getPropertyPath(), $name, $key, gettype($key_definition)));
                }
            }
        }
        $this->processRequiredKeyFlags($definition);
        parent::__construct($definition, $name, $parent);
    }
    
    /**
     * {@inheritdoc}
     */
    protected function getElementDefinition($key) {
        $value = $this->value[$key] ?? NULL;
        $definition = $this->definition['mapping'][$key] ?? [];
        return $this->buildDataDefinition($definition, $value, $key);
    }
    
    /**
     * Gets all keys allowed in this mapping.
     *
     * @return string[]
     *   A list of keys allowed in this mapping.
     */
    public function getValidKeys() : array {
        $all_keys = $this->getDefinedKeys();
        return array_keys($all_keys);
    }
    
    /**
     * Gets all required keys in this mapping.
     *
     * @return string[]
     *   A list of keys required in this mapping.
     */
    public function getRequiredKeys() : array {
        $all_keys = $this->getDefinedKeys();
        $required_keys = array_filter($all_keys, fn(array $schema_definition): bool => $schema_definition['requiredKey']);
        return array_keys($required_keys);
    }
    
    /**
     * Gets the keys defined for this mapping (locally defined + inherited).
     *
     * @return array
     *   Raw schema definitions: keys are mapping keys, values are their
     *   definitions.
     */
    protected function getDefinedKeys() : array {
        $definition = $this->getDataDefinition();
        return $definition->toArray()['mapping'];
    }
    
    /**
     * Gets all dynamically valid keys.
     *
     * When the `type` of the mapping is dynamic itself. For example: the settings
     * associated with a FieldConfig depend on what kind of field it is (i.e.,
     * which field plugin it uses).
     *
     * Other examples:
     * - CKEditor 5 uses 'ckeditor5.plugin.[%key]'; the mapping is stored in a
     *   sequence, and `[%key]` is replaced by the mapping's key in that sequence.
     * - third party settings use '[%parent.%parent.%type].third_party.[%key]';
     *   `[%parent.%parent.%type]` is replaced by the type of the mapping two
     *   levels up. For example, 'node.type.third_party.[%key]'.
     * - field instances' default values have a type of
     *   'field.value.[%parent.%parent.field_type]'. This uses the value of the
     *   `field_type` key from the mapping two levels up.
     * - Views filters have a type of 'views.filter.[plugin_id]'; `[plugin_id]` is
     *   replaced by the value of the mapping's `plugin_id` key.
     *
     * In each of these examples, the mapping may have keys that are dynamically
     * valid, meaning that which keys are considered valid may depend on other
     * values in the tree.
     *
     * @return string[][]
     *   A list of dynamically valid keys. An array with:
     *   - a key for every possible resolved type
     *   - the corresponding value an array of the additional mapping keys that
     *     are supported for this resolved type
     *
     * @see \Drupal\Core\Config\TypedConfigManager::resolveDynamicTypeName()
     * @see \Drupal\Core\Config\TypedConfigManager::resolveExpression()
     * @see https://www.drupal.org/files/ConfigSchemaCheatSheet2.0.pdf
     */
    public function getDynamicallyValidKeys() : array {
        $parent_data_def = $this->getParent()?->getDataDefinition();
        if ($parent_data_def === NULL) {
            return [];
        }
        // Use the parent data definition to determine the type of this mapping
        // (including the dynamic placeholders). For example:
        // - `editor.settings.[%parent.editor]`
        // - `editor.image_upload_settings.[status]`.
        $original_mapping_type = match (TRUE) {    $parent_data_def instanceof MapDataDefinition => $parent_data_def->toArray()['mapping'][$this->getName()]['type'],
            $parent_data_def instanceof SequenceDataDefinition => $parent_data_def->toArray()['sequence']['type'],
            default => throw new \LogicException('Invalid config schema detected.'),
        
        };
        // If this mapping's type isn't dynamic, there's nothing to do.
        if (!str_contains($original_mapping_type, ']')) {
            return [];
        }
        elseif (str_starts_with($original_mapping_type, '[')) {
            return [];
        }
        // Expand the dynamic placeholders to find all mapping types derived from
        // the original mapping type. To continue the previous example:
        // - `editor.settings.unicorn`
        // - `editor.image_upload_settings.*`
        // - `editor.image_upload_settings.1`
        $possible_types = $this->getPossibleTypes($original_mapping_type);
        // TRICKY: it is tempting to not consider this a dynamic type if only one
        // concrete type exists. But that would lead to different validation errors
        // when modules are installed or uninstalled.
        assert(!empty($possible_types));
        // Determine all valid keys, across all possible types.
        $typed_data_manager = $this->getTypedDataManager();
        $all_type_definitions = $typed_data_manager->getDefinitions();
        $possible_type_definitions = array_intersect_key($all_type_definitions, array_fill_keys($possible_types, TRUE));
        // TRICKY: \Drupal\Core\Config\TypedConfigManager::getDefinition() does the
        // necessary resolving, but TypedConfigManager::getDefinitions() does not! 🤷‍♂️
        // @see \Drupal\Core\Config\TypedConfigManager::getDefinitionWithReplacements()
        // @see ::getValidKeys()
        $valid_keys_per_type = [];
        foreach (array_keys($possible_type_definitions) as $possible_type_name) {
            $valid_keys_per_type[$possible_type_name] = array_keys($typed_data_manager->getDefinition($possible_type_name)['mapping'] ?? []);
        }
        // From all valid keys across all types, get the ones for the fallback type:
        // its keys are inherited by all type definitions and are therefore always
        // ("statically") valid. Not all types have a fallback type.
        // @see \Drupal\Core\Config\TypedConfigManager::getDefinitionWithReplacements()
        $fallback_type = $typed_data_manager->findFallback($original_mapping_type);
        $valid_keys_everywhere = array_intersect_key($valid_keys_per_type, [
            $fallback_type => NULL,
        ]);
        assert(count($valid_keys_everywhere) <= 1);
        $statically_required_keys = NestedArray::mergeDeepArray($valid_keys_everywhere);
        // Now that statically valid keys are known, determine which valid keys are
        // only valid in *some* cases: remove the statically valid keys from every
        // per-type array of valid keys.
        $valid_keys_some = array_diff_key($valid_keys_per_type, $valid_keys_everywhere);
        $valid_keys_some_processed = array_map(fn(array $keys) => array_values(array_filter($keys, fn(string $key) => !in_array($key, $statically_required_keys, TRUE))), $valid_keys_some);
        return $valid_keys_some_processed;
    }
    
    /**
     * Gets all optional keys in this mapping.
     *
     * @return string[]
     *   A list of optional keys given the values in this mapping.
     */
    public function getOptionalKeys() : array {
        return array_values(array_diff($this->getValidKeys(), $this->getRequiredKeys()));
    }
    
    /**
     * Validates optional `requiredKey` flags, guarantees one will be set.
     *
     * For each key-value pair:
     * - If the `requiredKey` flag is set, it must be `false`, to avoid pointless
     *   information in the schema.
     * - If the `requiredKey` flag is not set and the `deprecated` flag is set,
     *   this will set `requiredKey: false`: deprecated keys are always optional.
     * - If the `requiredKey` flag is not set, nor the `deprecated` flag,
     *   will set `requiredKey: true`.
     *
     * @param \Drupal\Core\TypedData\MapDataDefinition $definition
     *   The config schema definition for a `type: mapping`.
     *
     * @return void
     *
     * @throws \LogicException
     *   Thrown when `requiredKey: true` is specified.
     */
    protected function processRequiredKeyFlags(MapDataDefinition $definition) : void {
        foreach ($definition['mapping'] as $key => $key_definition) {
            // Validates `requiredKey` flag in mapping definitions.
            if (array_key_exists('requiredKey', $key_definition) && $key_definition['requiredKey'] !== FALSE) {
                throw new \LogicException('The `requiredKey` flag must either be omitted or have `false` as the value.');
            }
            // Generates the `requiredKey` flag if it is not set.
            if (!array_key_exists('requiredKey', $key_definition)) {
                // Required by default, unless this key is marked as deprecated.
                // @see https://www.drupal.org/node/3129881
                $definition['mapping'][$key]['requiredKey'] = !array_key_exists('deprecated', $key_definition);
            }
        }
    }
    
    /**
     * Returns all possible types for the type with the given name.
     *
     * @param string $name
     *   Configuration name or key.
     *
     * @return string[]
     *   All possible types for a given type. For example,
     *   `core_date_format_pattern.[%parent.locked]` will return:
     *   - `core_date_format_pattern.0`
     *   - `core_date_format_pattern.1`
     *   If a fallback name is available, that will be returned too. In this
     *   example, that would be `core_date_format_pattern.*`.
     */
    protected function getPossibleTypes(string $name) : array {
        // First, parse from e.g.
        // `module.something.foo_[%parent.locked]`
        // this:
        // `[%parent.locked]`
        // or from
        // `[%parent.%parent.%type].third_party.[%key]`
        // this:
        // `[%parent.%parent.%type]` and `[%key]`.
        // And collapse all these to just `[]`.
        // @see \Drupal\Core\Config\TypedConfigManager::replaceVariable()
        $matches = [];
        if (preg_match_all('/(\\[[^\\]]+\\])/', $name, $matches) >= 1) {
            $name = str_replace($matches[0], '[]', $name);
        }
        // Then, replace all `[]` occurrences with `.*` and escape all periods for
        // use in a regex. So:
        // `module\.something\.foo_.*`
        // or
        // `.*\.third_party\..*`
        $regex = str_replace([
            '.',
            '[]',
        ], [
            '\\.',
            '.*',
        ], $name);
        // Now find all possible types:
        // 1. `module.something.foo_foo`, `module.something.foo_bar`, etc.
        $possible_types = array_filter(array_keys($this->getTypedDataManager()
            ->getDefinitions()), fn(string $type) => preg_match("/^{$regex}\$/", $type) === 1);
        // 2. The fallback: `module.something.*` — if no concrete definition for it
        // exists.
        $fallback_type = $this->getTypedDataManager()
            ->findFallback($name);
        if ($fallback_type && !in_array($fallback_type, $possible_types, TRUE)) {
            $possible_types[] = $fallback_type;
        }
        return $possible_types;
    }

}