WordPress at a glance

register_taxonomy() WP 1.0

Creates or modifies a taxonomy object.

Note: Do not use before the 'init' hook.

A simple function for creating or modifying a taxonomy object based on the parameters given. If modifying an existing taxonomy object, note that the $object_type value from the original registration will be overwritten.

Works based on: WP_Taxonomy()
Hooks from the function
Return

WP_Error/null. WP_Error, if errors.

Usage

register_taxonomy( $taxonomy, $object_type, $args );
$taxonomy(string) (required)
Taxonomy key, must not exceed 32 characters.
$object_type(array/string) (required)
Object type or array of object types with which the taxonomy should be associated.
$args(array/string)

Array or query string of arguments for registering a taxonomy.

  • $labels (array)
    An array of labels for this taxonomy. By default, Tag labels are used for non-hierarchical taxonomies, and Category labels are used for hierarchical taxonomies. See accepted values in get_taxonomy_labels().
    Default: empty array

  • $description (string)
    A short descriptive summary of what the taxonomy is for.
    Default: ''

  • $public (true/false)
    Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users. The default settings of $publicly_queryable, $show_ui, and $show_in_nav_menus are inherited from $public.

  • $publicly_queryable (true/false)
    Whether the taxonomy is publicly queryable. If not set, the default is inherited from $public

  • $hierarchical (true/false)
    Whether the taxonomy is hierarchical.
    Default: false

  • $show_ui (true/false)
    Whether to generate and allow a UI for managing terms in this taxonomy in the admin. If not set, the default is inherited from $public (default true).

  • $show_in_menu (true/false)
    Whether to show the taxonomy in the admin menu. If true, the taxonomy is shown as a submenu of the object type menu. If false, no menu is shown. $show_ui must be true. If not set.
    Default: inherited from $show_ui (default true)

  • $show_in_nav_menus (true/false)
    Makes this taxonomy available for selection in navigation menus. If not set, the default is inherited from $public (default true).

  • $show_in_rest (true/false)
    Whether to include the taxonomy in the REST API.

  • $rest_base (string)
    To change the base url of REST API route.
    Default: $taxonomy

  • $rest_controller_class (string)
    REST API Controller class name.
    Default: 'WP_REST_Terms_Controller'

  • $show_tagcloud (true/false)
    Whether to list the taxonomy in the Tag Cloud Widget controls. If not set, the default is inherited from $show_ui (default true).

  • $show_in_quick_edit (true/false)
    Whether to show the taxonomy in the quick/bulk edit panel. It not set, the default is inherited from $show_ui (default true).

  • $show_admin_column (true/false)
    Whether to display a column for the taxonomy on its post type listing screens.
    Default: false

  • $meta_box_cb (true/false/callable)
    Provide a callback function for the meta box display. If not set, post_categories_meta_box() is used for hierarchical taxonomies, and post_tags_meta_box() is used for non-hierarchical. If false, no meta box is shown.

  • $meta_box_sanitize_cb (callable)
    Callback function for sanitizing taxonomy data saved from a meta box. If no callback is defined, an appropriate one is determined based on the value of $meta_box_cb.

  • $capabilities (array)
    Array of capabilities for this taxonomy.

    • $manage_terms (string)
      Default 'manage_categories'.

    • $edit_terms (string)
      Default 'manage_categories'.

    • $delete_terms (string)
      Default 'manage_categories'.

    • $assign_terms (string)
      Default 'edit_posts'.
  • $rewrite (true/false/array)
    Triggers the handling of rewrites for this taxonomy. To prevent rewrite, set to false. To specify rewrite rules, an array can be passed with any of these keys:

    • $slug (string)
      Customize the permastruct slug.
      Default: $taxonomy key

    • $with_front (true/false)
      Should the permastruct be prepended with WP_Rewrite::$front.
      Default: true

    • $hierarchical (true/false)
      Either hierarchical rewrite tag or not.
      Default: false

    • $ep_mask (int)
      Assign an endpoint mask.
      Default: EP_NONE

    Default: true, using $taxonomy as slug

  • $query_var (string)
    Sets the query var key for this taxonomy. If false, a taxonomy cannot be loaded at ?{query_var}={term_slug}. If a string, the query ?{query_var}={term_slug} will be valid.
    Default: $taxonomy key

  • $update_count_callback (callable)
    Works much like a hook, in that it will be called when the count is updated. Default _update_generic_term_count() for taxonomies attached to other object types, such as users.
    Default: _update_post_term_count() for taxonomies attached to post types, which confirms that the objects are published before counting them

  • $_builtin (true/false)
    This taxonomy is a "built-in" taxonomy. INTERNAL USE ONLY! Default false.

Default: array()

Notes

  • Global. Array. $wp_taxonomies Registered taxonomies.

Changelog

Since 2.3.0 Introduced.
Since 4.2.0 Introduced show_in_quick_edit argument.
Since 4.4.0 The show_ui argument is now enforced on the term editing screen.
Since 4.4.0 The public argument now controls whether the taxonomy can be queried on the front end.
Since 4.5.0 Introduced publicly_queryable argument.
Since 4.7.0 Introduced show_in_rest, 'rest_base' and 'rest_controller_class' arguments to register the Taxonomy in REST API.
Since 5.1.0 Introduced meta_box_sanitize_cb argument.

Code of register taxonomy: wp-includes/taxonomy.php WP 5.2.2

<?php
function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
	global $wp_taxonomies;

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

	$args = wp_parse_args( $args );

	if ( empty( $taxonomy ) || strlen( $taxonomy ) > 32 ) {
		_doing_it_wrong( __FUNCTION__, __( 'Taxonomy names must be between 1 and 32 characters in length.' ), '4.2.0' );
		return new WP_Error( 'taxonomy_length_invalid', __( 'Taxonomy names must be between 1 and 32 characters in length.' ) );
	}

	$taxonomy_object = new WP_Taxonomy( $taxonomy, $object_type, $args );
	$taxonomy_object->add_rewrite_rules();

	$wp_taxonomies[ $taxonomy ] = $taxonomy_object;

	$taxonomy_object->add_hooks();

	/**
	 * Fires after a taxonomy is registered.
	 *
	 * @since 3.3.0
	 *
	 * @param string       $taxonomy    Taxonomy slug.
	 * @param array|string $object_type Object type or array of object types.
	 * @param array        $args        Array of taxonomy registration arguments.
	 */
	do_action( 'registered_taxonomy', $taxonomy, $object_type, (array) $taxonomy_object );
}

Related Functions

From tag: WP extension (enhancement)

More from category: Any taxonomy

No comments
    Hello, !     Log In . Register