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.
$taxonomystringrequired
$object_typearray|stringrequired
$argsarray|stringoptional
labels string[]description stringpublic bool$publicly_queryable, $show_ui, and $show_in_nav_menus are inherited from $public.publicly_queryable bool$public
hierarchical boolshow_ui bool$public (default true).show_in_menu bool$show_ui must be true. If not set, default is inherited from $show_ui (default true).show_in_nav_menus bool$public (default true).show_in_rest boolrest_base stringrest_namespace stringrest_controller_class stringshow_tagcloud bool$show_ui (default true).show_in_quick_edit bool$show_ui (default true).show_admin_column boolmeta_box_cb bool|callablemeta_box_sanitize_cb callable$meta_box_cb.capabilities string[]manage_terms string'manage_categories'.edit_terms string'manage_categories'.delete_terms string'manage_categories'.assign_terms string'edit_posts'.rewrite bool|arrayslug string$taxonomy key.with_front boolhierarchical boolep_mask intEP_NONE.query_var string|bool$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_callback callabledefault_term string|arrayname stringslug stringdescription stringsort boolwp_set_object_terms(). Default null which equates to false.args arraywp_get_object_terms() for this taxonomy._builtin boolDefault:array()
This function adds or overwrites a taxonomy. It takes in a name, an object name that it affects, and an array of parameters. It does not return anything.
Care should be used in selecting a taxonomy name so that it does not conflict with other taxonomies, post types, and reserved WordPress public and private query variables. A complete list of those is described in the Reserved Terms section. In particular, capital letters should be avoided.
Better be safe than sorry when registering custom taxonomies for custom post types. Use register_taxonomy_for_object_type() right after the function to interconnect them. Else you could run into minetraps where the post type isn’t attached inside filter callback that run during parse_request or pre_get_posts.
_x( 'Post Tags', 'taxonomy general name' ) or _x( 'Categories', 'taxonomy general name' ). When internationalizing this string, please use a gettext context matching your post type. Example: _x('Writers', 'taxonomy general name');
_x( 'Post Tag', 'taxonomy singular name' ) or _x( 'Category', 'taxonomy singular name' ). When internationalizing this string, please use a gettext context matching your post type. Example: _x('Writer', 'taxonomy singular name');
__( 'All Tags' ) or __( 'All Categories' )
__( 'Edit Tag' ) or __( 'Edit Category' )
__( 'View Tag' ) or __( 'View Category' )
__( 'Update Tag' ) or __( 'Update Category' )
__( 'Add New Tag' ) or __( 'Add New Category' )
__( 'New Tag Name' ) or __( 'New Category Name' )
__( 'Parent Category' )
parent_item, but with colon : in the end null, __( 'Parent Category:' )
__( 'Search Tags' ) or __( 'Search Categories' )
__( 'Popular Tags' ) or null__( 'Separate tags with commas' ), or null__( 'Add or remove tags' ) or null__( 'Choose from the most used tags' ) or null__( 'No tags found.' ) or __( 'No categories found.' )
__( ' Back to tags' ) or __( ' Back to categories' )
Note: Defaults to the categories meta box (post_categories_meta_box() in meta-boxes.php) for hierarchical taxonomies and the tags meta box (post_tags_meta_box() ) for non-hierarchical taxonomies. No meta box is shown if set to false.
Note: Hierarchical taxonomies will have a list with checkboxes to select an existing category in the taxonomy admin box on the post edit page (like default post categories). Non-hierarchical taxonomies will just have an empty text field to type-in taxonomy terms to associate with the post (like default post tags).
Note: While the default is '', when actually performing the count update in wp_update_term_count_now() , if the taxonomy is only attached to post types (as opposed to other WordPress objects, like user), the built-in _update_post_term_count() function will be used to count only published posts associated with that term, otherwise _update_generic_term_count() will be used instead, that does no such checking.
This is significant in the case of attachments. Because an attachment is a type of post, the default _update_post_term_count() will be used. However, this may be undesirable, because this will only count attachments that are actually attached to another post (like when you insert an image into a post). This means that attachments that you simply upload to WordPress using the Media Library, but do not actually attach to another post will not be counted. If your intention behind associating a taxonomy with attachments was to leverage the Media Library as a sort of Document Management solution, you are probably more interested in the counts of unattached Media items, than in those attached to posts. In this case, you should force the use of _update_generic_term_count() by setting ‘_update_generic_term_count’ as the value for update_count_callback.
Another important consideration is that _update_post_term_count() only counts published posts. If you are using custom statuses, or using custom post types where being published is not necessarily a consideration for being counted in the term count, then you will need to provide your own callback that doesn’t include the post_status portion of the where clause.
Note: The query_var is used for direct queries through WP_Query like new WP_Query(array('people'=>$person_name)) and URL queries like /?people=$person_name. Setting query_var to false will disable these methods, but you can still fetch posts with an explicit WP_Query taxonomy query like WP_Query(array('taxonomy'=>'people', 'term'=>$person_name)).
Note: You may need to flush the rewrite rules after changing this. You can do it manually by going to the Permalink Settings page and re-saving the rules — you don’t need to change them — or by calling $wp_rewrite->flush_rules(). You should only flush the rules once after the taxonomy has been created, not every time the plugin/theme loads.
Avoiding the following reserved terms is particularly important if you are passing the term through the $_GET or $_POST array. Doing so can cause WordPress to respond with a 404 error without any other hint or explanation.
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();
// Add default term.
if ( ! empty( $taxonomy_object->default_term ) ) {
$term = term_exists( $taxonomy_object->default_term['name'], $taxonomy );
if ( $term ) {
update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );
} else {
$term = wp_insert_term(
$taxonomy_object->default_term['name'],
$taxonomy,
array(
'slug' => sanitize_title( $taxonomy_object->default_term['slug'] ),
'description' => $taxonomy_object->default_term['description'],
)
);
// Update `term_id` in options.
if ( ! is_wp_error( $term ) ) {
update_option( 'default_term_' . $taxonomy_object->name, $term['term_id'] );
}
}
}
/**
* 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 );
/**
* Fires after a specific taxonomy is registered.
*
* The dynamic portion of the filter name, `$taxonomy`, refers to the taxonomy key.
*
* Possible hook names include:
*
* - `registered_taxonomy_category`
* - `registered_taxonomy_post_tag`
*
* @since 6.0.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}", $taxonomy, $object_type, (array) $taxonomy_object );
return $taxonomy_object;
}
Fires after a taxonomy is registered.
Fires after a specific taxonomy is registered.
| Version | Description |
|---|---|
| 5.9.0 | Introduced rest_namespace argument. |
| 5.5.0 | Introduced default_term argument. |
| 5.4.0 | Added the registered taxonomy object as a return value. |
| 5.1.0 | Introduced meta_box_sanitize_cb argument. |
| 4.7.0 | Introduced show_in_rest, 'rest_base' and 'rest_controller_class' arguments to register the taxonomy in REST API. |
| 4.5.0 | Introduced publicly_queryable argument. |
| 4.4.0 | The public argument now controls whether the taxonomy can be queried on the front end. |
| 4.2.0 | Introduced show_in_quick_edit argument. |
| 2.3.0 | Introduced. |
You must log in before being able to contribute a note or feedback.
© 2003–2024 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/register_taxonomy?replytocom=3251