register_taxonomy( string $taxonomy, array|string $object_type, array|string $args = array() ): WP_Taxonomy|WP_Error

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

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 value

WP_Taxonomy|WP_Error

The registered taxonomy object on success, WP_Error object on failure.

Performance profile

How much work a call to register_taxonomy() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_terms().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

28–86

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 111.

Plugin surface

2 hooks

Third-party callbacks on 'registered_taxonomy', 'registered_taxonomy_{$taxonomy}' run inside this call, and their cost is not bounded by anything here.

Called by

1

1 place in core call this, so the cost is paid more often than your own code shows.

What it touches

• optionoption read or writeupdate_option()called directly
• hookthird-party callbacksdo_action()called directly
• querycontent queryget_terms()one call below register_taxonomy()
• serializeserialisationmaybe_serialize()one call below register_taxonomy()
• cacheobject cachewp_cache_get()one call below register_taxonomy()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 5 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost register_taxonomy() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 2

2 hooks fire while register_taxonomy() runs, in this order:

1. 1
   do_action( registered_taxonomy )actionline 570 (+52 into the body)

   Fires after a taxonomy is registered.

2. 2
   do_action( registered_taxonomy_{$taxonomy} )actionline 588 (+70 into the body)

   Fires after a specific taxonomy is registered.

Uses · 11

• wp_parse_args()Merges user defined arguments into defaults array.
• _doing_it_wrong()Marks something as being incorrectly called.
• __()Retrieves the translation of $text.
• term_exists()Determines whether a taxonomy term exists.
• update_option()Updates the value of an option that was already added.
• wp_insert_term()Adds a new term to the database.
• sanitize_title()Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• do_action()Calls the callback functions that have been added to an action hook.
• WP_Error::__construct()Initializes the error.
• WP_Taxonomy::__construct()Constructor.

Used by · 1

• create_initial_taxonomies()Creates the initial taxonomies.

Source code

View on Trac ↗View on GitHub ↗

518function register_taxonomy( $taxonomy, $object_type, $args = array() ) {519	global $wp_taxonomies;520 521	if ( ! is_array( $wp_taxonomies ) ) {522		$wp_taxonomies = array();523	}524 525	$args = wp_parse_args( $args );526 527	if ( empty( $taxonomy ) || strlen( $taxonomy ) > 32 ) {528		_doing_it_wrong( __FUNCTION__, __( 'Taxonomy names must be between 1 and 32 characters in length.' ), '4.2.0' );529		return new WP_Error( 'taxonomy_length_invalid', __( 'Taxonomy names must be between 1 and 32 characters in length.' ) );530	}531 532	$taxonomy_object = new WP_Taxonomy( $taxonomy, $object_type, $args );533	$taxonomy_object->add_rewrite_rules();534 535	$wp_taxonomies[ $taxonomy ] = $taxonomy_object;536 537	$taxonomy_object->add_hooks();538 539	// Add default term.540	if ( ! empty( $taxonomy_object->default_term ) ) {541		$term = term_exists( $taxonomy_object->default_term['name'], $taxonomy );542		if ( $term ) {543			update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );544		} else {545			$term = wp_insert_term(546				$taxonomy_object->default_term['name'],547				$taxonomy,548				array(549					'slug'        => sanitize_title( $taxonomy_object->default_term['slug'] ),550					'description' => $taxonomy_object->default_term['description'],551				)552			);553 554			// Update `term_id` in options.555			if ( ! is_wp_error( $term ) ) {556				update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );557			}558		}559	}560 561	/**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	 */570	do_action( 'registered_taxonomy', $taxonomy, $object_type, (array) $taxonomy_object );571 572	/**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	 */588	do_action( "registered_taxonomy_{$taxonomy}", $taxonomy, $object_type, (array) $taxonomy_object );589 590	return $taxonomy_object;591}

Changelog

Introduced in 5.9.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

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.