register_theme_feature() │ WP 5.5.0

Registers a theme feature for use in add_theme_support().

This does not indicate that the active theme supports the feature, it only describes the feature's supported options.

No Hooks.

Returns

true|WP_Error. True if the theme feature was successfully registered, a WP_Error object if not.

Usage

register_theme_feature( $feature, $args );

$feature(string) (required)

The name uniquely identifying the feature. See add_theme_support() for the list of possible values.

$args(array)

Data used to describe the theme.

Default: array()

• type(string)
  The type of data associated with this feature. Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.
  Default: 'boolean'

• variadic(true|false)
  Does this feature utilize the variadic support of add_theme_support(), or are all arguments specified as the second parameter. Must be used with the "array" type.

• description(string)
  A short description of the feature. Included in the Themes REST API schema. Intended for developers.

• show_in_rest(true|false|array)
  Whether this feature should be included in the Themes REST API endpoint. When registering an 'array' or 'object' type, this argument must be an array with the 'schema' key.
  Default: not being included

  • schema(array)
    Specifies the JSON Schema definition describing the feature. If any objects in the schema do not include the 'additionalProperties' keyword, it is set to false.

  • name(string)
    An alternate name to be used as the property name in the REST API.

  • prepare_callback(callable)
    A function used to format the theme support in the REST API. Receives the raw theme support value.

Notes

• See: add_theme_support()
• Global. Array. $_wp_registered_theme_features

Changelog

register_theme_feature() register theme feature code ^{WP 6.8.1}

function register_theme_feature( $feature, $args = array() ) {
	global $_wp_registered_theme_features;

	if ( ! is_array( $_wp_registered_theme_features ) ) {
		$_wp_registered_theme_features = array();
	}

	$defaults = array(
		'type'         => 'boolean',
		'variadic'     => false,
		'description'  => '',
		'show_in_rest' => false,
	);

	$args = wp_parse_args( $args, $defaults );

	if ( true === $args['show_in_rest'] ) {
		$args['show_in_rest'] = array();
	}

	if ( is_array( $args['show_in_rest'] ) ) {
		$args['show_in_rest'] = wp_parse_args(
			$args['show_in_rest'],
			array(
				'schema'           => array(),
				'name'             => $feature,
				'prepare_callback' => null,
			)
		);
	}

	if ( ! in_array( $args['type'], array( 'string', 'boolean', 'integer', 'number', 'array', 'object' ), true ) ) {
		return new WP_Error(
			'invalid_type',
			__( 'The feature "type" is not valid JSON Schema type.' )
		);
	}

	if ( true === $args['variadic'] && 'array' !== $args['type'] ) {
		return new WP_Error(
			'variadic_must_be_array',
			__( 'When registering a "variadic" theme feature, the "type" must be an "array".' )
		);
	}

	if ( false !== $args['show_in_rest'] && in_array( $args['type'], array( 'array', 'object' ), true ) ) {
		if ( ! is_array( $args['show_in_rest'] ) || empty( $args['show_in_rest']['schema'] ) ) {
			return new WP_Error(
				'missing_schema',
				__( 'When registering an "array" or "object" feature to show in the REST API, the feature\'s schema must also be defined.' )
			);
		}

		if ( 'array' === $args['type'] && ! isset( $args['show_in_rest']['schema']['items'] ) ) {
			return new WP_Error(
				'missing_schema_items',
				__( 'When registering an "array" feature, the feature\'s schema must include the "items" keyword.' )
			);
		}

		if ( 'object' === $args['type'] && ! isset( $args['show_in_rest']['schema']['properties'] ) ) {
			return new WP_Error(
				'missing_schema_properties',
				__( 'When registering an "object" feature, the feature\'s schema must include the "properties" keyword.' )
			);
		}
	}

	if ( is_array( $args['show_in_rest'] ) ) {
		if ( isset( $args['show_in_rest']['prepare_callback'] )
			&& ! is_callable( $args['show_in_rest']['prepare_callback'] )
		) {
			return new WP_Error(
				'invalid_rest_prepare_callback',
				sprintf(
					/* translators: %s: prepare_callback */
					__( 'The "%s" must be a callable function.' ),
					'prepare_callback'
				)
			);
		}

		$args['show_in_rest']['schema'] = wp_parse_args(
			$args['show_in_rest']['schema'],
			array(
				'description' => $args['description'],
				'type'        => $args['type'],
				'default'     => false,
			)
		);

		if ( is_bool( $args['show_in_rest']['schema']['default'] )
			&& ! in_array( 'boolean', (array) $args['show_in_rest']['schema']['type'], true )
		) {
			// Automatically include the "boolean" type when the default value is a boolean.
			$args['show_in_rest']['schema']['type'] = (array) $args['show_in_rest']['schema']['type'];
			array_unshift( $args['show_in_rest']['schema']['type'], 'boolean' );
		}

		$args['show_in_rest']['schema'] = rest_default_additional_properties_to_false( $args['show_in_rest']['schema'] );
	}

	$_wp_registered_theme_features[ $feature ] = $args;

	return true;
}