• File: plain-schema-validator.php
  • Full Path: /home/slvgwrnz/public_html/wp-content/plugins/elementor/modules/mcp/abilities/utils/plain-schema-validator.php
  • Date Modified: 11/05/2026 9:17 AM
  • File size: 6.46 KB
  • MIME-type: text/x-php
  • Charset: utf-8
<?php

namespace Elementor\Modules\Mcp\Abilities\Utils;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Accepts or rejects a raw plain setting value against the same JSON schema `get-widget-schemas`
 * publishes, before any resolver converts it, so the error the agent gets names a keyword it can see.
 */
class Plain_Schema_Validator {

	const ENVELOPE_TYPE_KEY = '$$type';

	const ANY_TYPE = [ 'array', 'object', 'string', 'number', 'integer', 'boolean', 'null' ];

	const STRING_OR_NUMBER = [ 'string', 'number' ];

	const COMBINING_KEYWORDS = [ 'anyOf', 'oneOf' ];

	const UNLISTED_KEY_ERROR_CODES = [ 'rest_additional_properties_forbidden', 'rest_no_matching_schema' ];

	private bool $lenient;

	private function __construct( bool $lenient ) {
		$this->lenient = $lenient;
	}

	public static function strict(): self {
		return new self( false );
	}

	/**
	 * Keeps the V4 write path's existing tolerance: unlisted object keys are left for the caller to
	 * drop with a warning, numbers are accepted where a string is published, null object keys count
	 * as not set, and `$$type` envelopes are left for `Props_Parser`.
	 */
	public static function lenient(): self {
		return new self( true );
	}

	/**
	 * @param mixed                $value  Raw value sent by the caller.
	 * @param array<string, mixed> $schema Published plain schema of the setting.
	 * @param string               $name   Setting key, used as the path root in error messages.
	 * @return array{value: mixed, error: string|null} The sanitized value, or the rejection reason.
	 */
	public function validate( $value, array $schema, string $name ): array {
		if ( $this->lenient && self::contains_envelope( $value ) ) {
			return self::accepted( $value );
		}

		if ( $this->lenient ) {
			$value = self::without_nested_nulls( $value );
		}

		$checked_schema = $this->prepare( $schema );
		$result = rest_validate_value_from_schema( $value, $checked_schema, $name );

		if ( is_wp_error( $result ) ) {
			return [
				'value' => null,
				'error' => self::error_message( $result, $value, $checked_schema, $name ),
			];
		}

		return self::accepted( rest_sanitize_value_from_schema( $value, $checked_schema, $name ) );
	}

	/**
	 * WordPress names only the unlisted key, not where it sits, which leaves the agent guessing in a list.
	 * Inside anyOf it also replaces the error code with the combining one.
	 *
	 * @param \WP_Error            $error
	 * @param mixed                $value
	 * @param array<string, mixed> $schema
	 * @param string               $name
	 */
	private static function error_message( \WP_Error $error, $value, array $schema, string $name ): string {
		$unlisted_key_path = in_array( $error->get_error_code(), self::UNLISTED_KEY_ERROR_CODES, true )
			? self::find_unlisted_key_path( $value, $schema, $name )
			: null;

		if ( null === $unlisted_key_path ) {
			return rtrim( $error->get_error_message(), '.' );
		}

		return sprintf( '%s is not a valid property of Object', $unlisted_key_path );
	}

	/**
	 * @param mixed $value
	 */
	private static function find_unlisted_key_path( $value, array $schema, string $path ): ?string {
		if ( ! is_array( $value ) ) {
			return null;
		}

		foreach ( self::COMBINING_KEYWORDS as $keyword ) {
			foreach ( $schema[ $keyword ] ?? [] as $branch ) {
				$found = is_array( $branch ) ? self::find_unlisted_key_path( $value, $branch, $path ) : null;

				if ( null !== $found ) {
					return $found;
				}
			}
		}

		$is_list = array_values( $value ) === $value;

		if ( $is_list && is_array( $schema['items'] ?? null ) ) {
			foreach ( $value as $index => $item ) {
				$found = self::find_unlisted_key_path( $item, $schema['items'], "{$path}[{$index}]" );

				if ( null !== $found ) {
					return $found;
				}
			}

			return null;
		}

		if ( $is_list && ! empty( $value ) ) {
			return null;
		}

		$properties = is_array( $schema['properties'] ?? null ) ? $schema['properties'] : [];

		foreach ( $value as $key => $child ) {
			if ( ! isset( $properties[ $key ] ) ) {
				if ( false === ( $schema['additionalProperties'] ?? null ) && ! isset( $schema['patternProperties'] ) ) {
					return "{$path}[{$key}]";
				}

				continue;
			}

			$found = is_array( $properties[ $key ] ) ? self::find_unlisted_key_path( $child, $properties[ $key ], "{$path}[{$key}]" ) : null;

			if ( null !== $found ) {
				return $found;
			}
		}

		return null;
	}

	/**
	 * @param mixed $value
	 * @return array{value: mixed, error: null}
	 */
	private static function accepted( $value ): array {
		return [
			'value' => $value,
			'error' => null,
		];
	}

	private function prepare( array $schema ): array {
		$is_combined = ! empty( array_intersect_key( $schema, array_flip( self::COMBINING_KEYWORDS ) ) );

		if ( ! isset( $schema['type'] ) && ! $is_combined ) {
			$schema['type'] = self::ANY_TYPE;
		}

		if ( $this->lenient && 'string' === ( $schema['type'] ?? null ) ) {
			$schema['type'] = self::STRING_OR_NUMBER;
		}

		if ( $this->lenient && false === ( $schema['additionalProperties'] ?? null ) ) {
			unset( $schema['additionalProperties'] );
		}

		foreach ( [ 'properties', 'patternProperties' ] as $keyword ) {
			if ( is_array( $schema[ $keyword ] ?? null ) ) {
				$schema[ $keyword ] = array_map( fn( $child ) => is_array( $child ) ? $this->prepare( $child ) : $child, $schema[ $keyword ] );
			}
		}

		foreach ( self::COMBINING_KEYWORDS as $keyword ) {
			if ( is_array( $schema[ $keyword ] ?? null ) ) {
				$schema[ $keyword ] = array_map( fn( $branch ) => is_array( $branch ) ? $this->prepare( $branch ) : $branch, $schema[ $keyword ] );
			}
		}

		if ( is_array( $schema['items'] ?? null ) ) {
			$schema['items'] = $this->prepare( $schema['items'] );
		}

		return $schema;
	}

	/**
	 * The V4 structure read returns unset object keys as null, and V4 props read null as not set.
	 *
	 * @param mixed $value
	 * @return mixed
	 */
	private static function without_nested_nulls( $value ) {
		if ( ! is_array( $value ) ) {
			return $value;
		}

		$is_list = array_values( $value ) === $value;
		$kept = [];

		foreach ( $value as $key => $child ) {
			if ( null === $child && ! $is_list ) {
				continue;
			}

			$kept[ $key ] = self::without_nested_nulls( $child );
		}

		return $kept;
	}

	/**
	 * @param mixed $value
	 */
	private static function contains_envelope( $value ): bool {
		if ( ! is_array( $value ) ) {
			return false;
		}

		if ( array_key_exists( self::ENVELOPE_TYPE_KEY, $value ) ) {
			return true;
		}

		foreach ( $value as $child ) {
			if ( self::contains_envelope( $child ) ) {
				return true;
			}
		}

		return false;
	}
}