SchemaCompatibilityChecker.php

<?php

namespace Drupal\Core\Theme\Component;

use Drupal\Core\Render\Component\Exception\IncompatibleComponentSchema;

/**
 * Checks whether two schemas are compatible.
 *
 * This is used during component replacement. We do not allow replacing a
 * component if the schemas are not compatible. Component authors must consider
 * their component schema as part of their module/theme API. Breaking changes
 * to the schema must be done in a new major version.
 */
class SchemaCompatibilityChecker {
    
    /**
     * Checks if the replacement schema is compatible with the old one.
     *
     * The goal is to ensure existing usages of the original component will not
     * break when the new component takes place.
     *
     * For the new schema to be compatible with the original it needs to accept
     * all the possible input that the original component allow. Any optional
     * props in the original component, not present in the replacement component
     * should be ignored and not cause validation errors.
     *
     * @param array $original_schema
     *   The schema to check compatibility against.
     * @param array $new_schema
     *   The new schema that should be compatible with.
     *
     * @throws \Drupal\Core\Render\Component\Exception\IncompatibleComponentSchema
     */
    public function isCompatible(array $original_schema, array $new_schema) : void {
        $error_messages = [];
        // First check the required properties.
        $error_messages = [
            $error_messages,
            $this->checkRequired($original_schema, $new_schema),
        ];
        // Next, compare the property types to ensure compatibility.
        $error_messages = [
            $error_messages,
            $this->checkSharedProperties($original_schema, $new_schema),
        ];
        // Finally, raise any potential issues that we might have detected.
        if (!empty($error_messages)) {
            $message = implode("\n", $error_messages);
            throw new IncompatibleComponentSchema($message);
        }
    }
    
    /**
     * Checks that the required properties are compatible.
     *
     * @param array $original_schema
     *   The original schema.
     * @param array $new_schema
     *   The schema of the replacement component.
     *
     * @return array
     *   The detected error messages, if any.
     */
    private function checkRequired(array $original_schema, array $new_schema) : array {
        $error_messages = [];
        $original_required = $original_schema['required'] ?? [];
        $new_required = $new_schema['required'] ?? [];
        $missing_required = array_diff($original_required, $new_required);
        if (!empty($missing_required)) {
            $error_messages[] = sprintf('Some of the required properties are missing in the new schema: [%s].', implode(', ', $missing_required));
        }
        $additional_required = array_diff($new_required, $original_required);
        if (!empty($additional_required)) {
            $error_messages[] = sprintf('Some of the new required properties are not allowed by the original schema: [%s].', implode(', ', $additional_required));
        }
        return $error_messages;
    }
    
    /**
     * Checks that the shared properties are compatible.
     *
     * @param array $original_schema
     *   The original schema.
     * @param array $new_schema
     *   The schema of the replacement component.
     *
     * @return array
     *   The detected error messages, if any.
     */
    private function checkSharedProperties(array $original_schema, array $new_schema) : array {
        $error_messages = [];
        $original_properties = $original_schema['properties'] ?? [];
        $new_properties = $new_schema['properties'] ?? [];
        $shared_properties = array_intersect(array_keys($original_properties), array_keys($new_properties));
        return array_reduce($shared_properties, function (array $errors, string $property_name) use ($original_properties, $new_properties) {
            $original_types = $original_properties[$property_name]['type'] ?? [];
            $new_types = $new_properties[$property_name]['type'] ?? [];
            // The type for the new property should, at least, accept all types for
            // the original property. Type in JSON Schema can be either a string or
            // an array of strings.
            $original_types = is_string($original_types) ? [
                $original_types,
            ] : $original_types;
            $new_types = is_string($new_types) ? [
                $new_types,
            ] : $new_types;
            $unsupported_types = array_diff($original_types, $new_types);
            if (!empty($unsupported_types)) {
                $errors[] = sprintf('Property "%s" does not support the types [%s]. These types are supported in the original schema and should be supported in the new schema for compatibility.', $property_name, implode(', ', $unsupported_types));
            }
            // If there are enums, those also need to be compatible.
            $original_enums = $original_properties[$property_name]['enum'] ?? [];
            $new_enums = $new_properties[$property_name]['enum'] ?? [];
            $unsupported_enums = array_diff($original_enums, $new_enums);
            if (!empty($unsupported_enums)) {
                $errors[] = sprintf('Property "%s" does not allow some necessary enum values [%s]. These are supported in the original schema and should be supported in the new schema for compatibility.', $property_name, implode(', ', $unsupported_enums));
            }
            // If the property is an object, then ensure sub-schema compatibility.
            $original_subproperties = $original_properties[$property_name]['properties'] ?? [];
            $new_subproperties = $new_properties[$property_name]['properties'] ?? [];
            if (!empty($original_subproperties) && !empty($new_subproperties)) {
                try {
                    $this->isCompatible($original_properties[$property_name], $new_properties[$property_name]);
                } catch (IncompatibleComponentSchema $exception) {
                    $errors[] = $exception->getMessage();
                }
            }
            return $errors;
        }, $error_messages);
    }

}