register_taxonomy – WordPress Function to Create or Modify Taxonomy

In WordPress, taxonomy is a grouping method for any post types.

WordPress have five built-in taxonomy categories, post tags, nav_menu, post_format and link_category. categories, post tags and post_format are used for post_type post, nav_menu is used for post_type nav_menu_item, and link_category is used for post_type link. When built-in taxonomy are not enough, custom taxonomies are created to group things some more way

Source Reference:

register_taxonomy function is located in wp-includes/taxonomy.php file on line 324. On the same file on line 44, you can check how WordPress has used register_taxonomy for creating the initial taxonomies like category, post_tag etc.

Using register_taxonomy:

To create a custom taxonomy or modify, use function register_taxonomy. This function accepts three arguments.

1. taxonomy name is an unique lowercase string, which is used later on to query terms under the taxonomy or assign a term for a post type. No number’s, no space & no upper case letters.

2. post object type is the post type name with whom the taxonomy will be used. The post type could be already registered or registered later.

3. third argument is an array of information that set the display name, usage restriction and some other thing.

Important options for the Third argument of register_taxonomy function:

hierarchical

Taxonomy has terms, generally which is visible with a post or custom post type. Ex: when we create a category English, the English is called a term for category taxonomy. We may need to create sub terms Ex: a new sub-term term US English and UK English under term English. This is where we need hierarchical argument. if we need parent => sub terms relation, hierarchical need to be set true, else set it false.

query_var

If you have used WordPress query_posts or get_posts function, you should have seen how you can do query for posts by a category name or id. Example: get_posts( array( ‘category_name’ => ‘uncategorized’) ). Here category_name is the query variable. So query_variable is extremely used on query. Setting query_var to false will restrict to query posts by using query_var.

If you register a custom taxonomy ex: taxonomy name is books an a term exists in this taxonomy tutorial and set the query_var argument to true, you can make a query for the posts belongs to the custom taxonomy (ex: “books” => “tutorial”). If 'query_var' argument is set to false, you can’t make this query as it won’t get you any result.

You only should set 'query_var' to 'false' if you want to use custom taxonomy with raw PHP MYSQL query, else set it to true for easy usage.

rewrite

Rewrite is the url formation you want to use for taxonomy terms. Example: A general category page url looks like – ‘http://SITEURL/category/the_category_term/’. Here ‘category’ is the taxonomy. And the the_category_term is a term slug. Each taxonomy display it’s terms in the format – http://SITEURL/taxonomy/term_slug/. To show a custom taxonomy terms with a different front rather than the taxonomy name, rewrite argument is used. setting this argument to false will use query variable on url like this: http://SITEURL/?taxonomy_name=the_term_name, rewrite accept parameter in array. Ex: ‘rewrite’ => array(‘slug’ => ‘the_slug_you_need_to_show_before_the_term_name’)

Example

Create a new taxonomy tutorial for default post_type post.

add_action( 'init', 'register_custom_taxonomies', 0 );
function register_custom_taxonomies()
{
    register_taxonomy( 'tutorial', 'post', array(
	"hierarchical" => true,
	"label" => "Tutorial",
	"singular_label" => "Tutorial",
	'query_var' => true,
	'rewrite' => array( 'slug' => 'tutorial', 'with_front' => false ),
	'public' => true,
	'show_ui' => true,
	'show_tagcloud' => true,
	'_builtin' => false,
	'show_in_nav_menus' => false
    ));
}

See here, we have called the 'register_taxonomy' function inside a new function 'register_custom_taxonomies'. As register taxonomy function need to be called after init action is fired. So we create a function and hooked it on init action event.

You can find the function reference at WordPress Codex Page.