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.
Parameters
$taxonomystring
Taxonomy key. Must not exceed 32 characters and may only contain lowercase alphanumeric characters, dashes, and underscores. See sanitize_key().
$object_typearray|string
Object type or array of object types with which the taxonomy should be associated.
$argsarray|stringoptional
Array or query string of arguments for registering a taxonomy.Default: array()
$labelsstring[]default: empty 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().
$descriptionstringdefault: empty
A short descriptive summary of what the taxonomy is for.
$publicbool
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_queryablebooldefault: false
Whether the taxonomy is publicly queryable. If not set, the default is inherited from $public @type bool $hierarchical Whether the taxonomy is hierarchical.
$show_uibool
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_menubool
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 is inherited from $show_ui (default true).
$show_in_nav_menusbool
Makes this taxonomy available for selection in navigation menus. If not set, the default is inherited from $public (default true).
$show_in_restbool
Whether to include the taxonomy in the REST API. Set this to true for the taxonomy to be available in the block editor.
$rest_basestringdefault: is $taxonomy
To change the base url of REST API route.
$rest_namespacestringdefault: is wp/v2
To change the namespace URL of REST API route.
$rest_controller_classstringdefault: is 'WP_REST_Terms_Controller'
REST API Controller class name.
$show_tagcloudbool
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_editbool
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_columnbooldefault: false
Whether to display a column for the taxonomy on its post type listing screens.
$meta_box_cbbool|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_cbcallable
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.
$capabilitiesstring[]
{ Array of capabilities for this taxonomy.
$manage_termsstringdefault: 'manage_categories'
$edit_termsstringdefault: 'manage_categories'
$delete_termsstringdefault: 'manage_categories'
$assign_termsstringdefault: $taxonomy key
Default 'edit_posts'. } @type bool|array $rewrite { Triggers the handling of rewrites for this taxonomy. Default true, using $taxonomy as slug. To prevent rewrite, set to false. To specify rewrite rules, an array can be passed with any of these keys: @type string $slug Customize the permastruct slug.
$with_frontbooldefault: true
Should the permastruct be prepended with WP_Rewrite::$front.
$hierarchicalbooldefault: false
Either hierarchical rewrite tag or not.
$ep_maskint
Assign an endpoint mask. Default EP_NONE. } @type string|bool $query_var Sets the query var key for this taxonomy. Default $taxonomy key. If false, a taxonomy cannot be loaded at ?{query_var}={term_slug}. If a string, the query ?{query_var}={term_slug} will be valid.
$update_count_callbackcallable
Works much like a hook, in that it will be called when the count is updated. Default _update_post_term_count() for taxonomies attached to post types, which confirms that the objects are published before counting them. Default _update_generic_term_count() for taxonomies attached to other object types, such as users.
$default_termstring|arraydefault: term to be used for the taxonomy
{
$namestring
Name of default term.
$slugstringdefault: empty
Slug for default term.
$descriptionstringdefault: null which equates to false
Description for default term. Default empty. } @type bool $sort Whether terms in this taxonomy should be sorted in the order they are provided to wp_set_object_terms().
$argsarray
Array of arguments to automatically use inside wp_get_object_terms() for this taxonomy.
$_builtinbooldefault: false
This taxonomy is a "built-in" taxonomy. INTERNAL USE ONLY!
Return
WP_Taxonomy|WP_Error
The registered taxonomy object on success, WP_Error object on failure.
Hooks fired · 2
2 hooks fire while register_taxonomy() runs, in this order:
518functionregister_taxonomy($taxonomy,$object_type,$args=array()){519global$wp_taxonomies;520521if(!is_array($wp_taxonomies)){522$wp_taxonomies=array();523}524525$args=wp_parse_args($args);526527if(empty($taxonomy)||strlen($taxonomy)>32){528_doing_it_wrong(__FUNCTION__,__('Taxonomy names must be between 1 and 32 characters in length.'),'4.2.0');529returnnewWP_Error('taxonomy_length_invalid',__('Taxonomy names must be between 1 and 32 characters in length.'));530}531532$taxonomy_object=newWP_Taxonomy($taxonomy,$object_type,$args);533$taxonomy_object->add_rewrite_rules();534535$wp_taxonomies[$taxonomy]=$taxonomy_object;536537$taxonomy_object->add_hooks();538539// Add default term.540if(!empty($taxonomy_object->default_term)){541$term=term_exists($taxonomy_object->default_term['name'],$taxonomy);542if($term){543update_option('default_term_'.$taxonomy_object->name,$term['term_id']);544}else{545$term=wp_insert_term(546$taxonomy_object->default_term['name'],547$taxonomy,548array(549'slug'=>sanitize_title($taxonomy_object->default_term['slug']),550'description'=>$taxonomy_object->default_term['description'],551)552);553554// Update `term_id` in options.555if(!is_wp_error($term)){556update_option('default_term_'.$taxonomy_object->name,$term['term_id']);557}558}559}560561/**562 * Fires after a taxonomy is registered.563 *564 * @since 3.3.0565 *566 * @param string $taxonomy Taxonomy slug.567 * @param array|string $object_type Object type or array of object types.568 * @param array $args Array of taxonomy registration arguments.569 */570do_action('registered_taxonomy',$taxonomy,$object_type,(array)$taxonomy_object);571572/**573 * Fires after a specific taxonomy is registered.574 *575 * The dynamic portion of the filter name, `$taxonomy`, refers to the taxonomy key.576 *577 * Possible hook names include:578 *579 * - `registered_taxonomy_category`580 * - `registered_taxonomy_post_tag`581 *582 * @since 6.0.0583 *584 * @param string $taxonomy Taxonomy slug.585 * @param array|string $object_type Object type or array of object types.586 * @param array $args Array of taxonomy registration arguments.587 */588do_action("registered_taxonomy_{$taxonomy}",$taxonomy,$object_type,(array)$taxonomy_object);589590return$taxonomy_object;591}
History
Introduced in 5.9.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
5.9.0
Introduced rest_namespace argument.from the docblock
5.5.0
Introduced default_term argument.from the docblock
5.4.0
Added the registered taxonomy object as a return value.from the docblock
5.1.0
Introduced meta_box_sanitize_cb argument.from the docblock
4.7.0
Introduced show_in_rest, 'rest_base' and 'rest_controller_class' arguments to register the taxonomy in REST API.from the docblock
4.5.0
Introduced publicly_queryable argument.from the docblock
4.4.0
The public argument now controls whether the taxonomy can be queried on the front end.from the docblock
4.4.0
The show_ui argument is now enforced on the term editing screen.from the docblock
4.2.0
Introduced show_in_quick_edit argument.from the docblock
2.3.0
Introduced.from the docblock
About this page
Parsed data
Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/taxonomy.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.