register_theme_feature( string $feature, array $args = array() ): true|WP_Error

Registers a theme feature for use in add_theme_support() .

Description

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

See also

Parameters

$featurestringrequired
The name uniquely identifying the feature. See add_theme_support() for the list of possible values.
More Arguments from add_theme_support( … $feature )The feature being added. Likely core values include:
  • 'admin-bar'
  • 'align-wide'
  • 'automatic-feed-links'
  • 'core-block-patterns'
  • 'custom-background'
  • 'custom-header'
  • 'custom-line-height'
  • 'custom-logo'
  • 'customize-selective-refresh-widgets'
  • 'custom-spacing'
  • 'custom-units'
  • 'dark-editor-style'
  • 'disable-custom-colors'
  • 'disable-custom-font-sizes'
  • 'editor-color-palette'
  • 'editor-gradient-presets'
  • 'editor-font-sizes'
  • 'editor-styles'
  • 'featured-content'
  • 'html5'
  • 'menus'
  • 'post-formats'
  • 'post-thumbnails'
  • 'responsive-embeds'
  • 'starter-content'
  • 'title-tag'
  • 'wp-block-styles'
  • 'widgets'
  • 'widgets-block-editor'
$argsarrayoptional
Data used to describe the theme.
  • type string
    The type of data associated with this feature.
    Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'. Defaults to 'boolean'.
  • variadic bool
    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 bool|array
    Whether this feature should be included in the Themes REST API endpoint.
    Defaults to not being included. When registering an ‘array’ or ‘object’ type, this argument must be an array with the ‘schema’ key.
    • 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.
More Arguments from add_theme_support( … $args )Optional extra arguments to pass along with certain features.

Default:array()

Return

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

Source

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;
}

Changelog

VersionDescription
5.5.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.