register_theme_feature

WordPress Version: 5.9

/**
 * Registers a theme feature for use in add_theme_support().
 *
 * This does not indicate that the current theme supports the feature, it only describes
 * the feature's supported options.
 *
 * @since 5.5.0
 *
 * @see add_theme_support()
 *
 * @global array $_wp_registered_theme_features
 *
 * @param string $feature The name uniquely identifying the feature. See add_theme_support()
 *                        for the list of possible values.
 * @param array  $args {
 *     Data used to describe the theme.
 *
 *     @type string     $type         The type of data associated with this feature.
 *                                    Valid values are 'string', 'boolean', 'integer',
 *                                    'number', 'array', and 'object'. Defaults to 'boolean'.
 *     @type bool       $variadic     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.
 *     @type string     $description  A short description of the feature. Included in
 *                                    the Themes REST API schema. Intended for developers.
 *     @type bool|array $show_in_rest {
 *         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.
 *
 *         @type array    $schema           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.
 *         @type string   $name             An alternate name to be used as the property name
 *                                          in the REST API.
 *         @type callable $prepare_callback A function used to format the theme support in the REST API.
 *                                          Receives the raw theme support value.
 *      }
 * }
 * @return true|WP_Error True if the theme feature was successfully registered, a WP_Error object if not.
 */
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;
}