Automattic\WooCommerce\Internal\Admin\Settings

SettingsUISchema::assert_valid_schema │ public static │ WC 11.2.0

Assert that a schema can safely cross the PHP-to-JavaScript boundary.

Compatibility normalization and request-owned shell defaults must run before this assertion. An invalid schema throws before it can be cached or emitted to JavaScript.

Method of the class: SettingsUISchema{}

No Hooks.

Returns

null. Nothing (null).

Usage

$result = SettingsUISchema::assert_valid_schema( $schema ): void;

$schema(array) (required)

Settings UI schema.

Changelog

SettingsUISchema::assert_valid_schema() SettingsUISchema::assert valid schema code ^{WC 11.2.1}

public static function assert_valid_schema( array $schema ): void {
	self::assert_non_empty_string( $schema['id'] ?? null, 'Schema id must be a non-empty string.' );

	foreach ( array( 'title', 'section' ) as $property ) {
		if ( array_key_exists( $property, $schema ) && ! is_string( $schema[ $property ] ) ) {
			throw self::invalid_schema( sprintf( 'Schema %s must be a string.', $property ) );
		}
	}

	if ( array_key_exists( 'section', $schema ) && '' === $schema['section'] ) {
		throw self::invalid_schema( 'Schema section must be a non-empty string.' );
	}

	self::assert_page_save_strategy( $schema['save'] ?? null );
	self::assert_shell( $schema['shell'] ?? null );

	if ( ! isset( $schema['groups'] ) || ! is_array( $schema['groups'] ) ) {
		throw self::invalid_schema( 'Schema groups must be a map.' );
	}

	foreach ( $schema['groups'] as $group_key => $group ) {
		$group_id = (string) $group_key;
		if ( '' === $group_id ) {
			throw self::invalid_schema( 'Group map keys must be non-empty strings.' );
		}

		if ( ! is_array( $group ) ) {
			throw self::invalid_schema( sprintf( 'Group "%s" must be an array.', $group_id ) );
		}

		self::assert_non_empty_string( $group['id'] ?? null, sprintf( 'Group "%s" id must be a non-empty string.', $group_id ) );
		if ( $group_id !== $group['id'] ) {
			throw self::invalid_schema( sprintf( 'Group map key "%s" must match group id "%s".', $group_id, $group['id'] ) );
		}
	}

	$field_ids        = array();
	$visibility_rules = array();
	foreach ( $schema['groups'] as $group ) {
		$group_id = $group['id'];
		self::assert_optional_strings( $group, array( 'title', 'description' ), sprintf( 'Group "%s"', $group_id ) );

		if ( ! isset( $group['fields'] ) || ! is_array( $group['fields'] ) || ! ArrayUtil::array_is_list( $group['fields'] ) ) {
			throw self::invalid_schema( sprintf( 'Group "%s" fields must be a list.', $group_id ) );
		}

		foreach ( $group['fields'] as $field_index => $field ) {
			if ( ! is_array( $field ) ) {
				throw self::invalid_schema( sprintf( 'Group "%s" field %d must be an array.', $group_id, $field_index ) );
			}

			self::assert_non_empty_string( $field['id'] ?? null, sprintf( 'Group "%s" field %d id must be a non-empty string.', $group_id, $field_index ) );
			$field_id = $field['id'];
			if ( isset( $field_ids[ $field_id ] ) ) {
				throw self::invalid_schema( sprintf( 'Field id "%s" is duplicated.', $field_id ) );
			}
			if ( isset( $schema['groups'][ $field_id ] ) ) {
				throw self::invalid_schema( sprintf( 'Field id "%s" collides with a group id.', $field_id ) );
			}

			$field_ids[ $field_id ] = true;
			self::assert_field( $field );
			if ( isset( $field['visibility'] ) ) {
				$visibility_rules[ $field_id ] = $field['visibility'];
			}
		}
	}

	foreach ( $visibility_rules as $field_id => $visibility ) {
		$controller = $visibility['controller'];
		if ( ! isset( $field_ids[ $controller ] ) ) {
			throw self::invalid_schema( sprintf( 'Field "%s" visibility controller "%s" does not reference a field.', $field_id, $controller ) );
		}
	}
}