3 * Taxonomy API: WP_Taxonomy class
11 * Core class used for interacting with taxonomies.
15 final class WP_Taxonomy {
26 * Name of the taxonomy shown in the menu. Usually plural.
35 * An array of labels for this taxonomy.
41 public $labels = array();
44 * A short descriptive summary of what the taxonomy is for.
50 public $description = '';
53 * Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users.
59 public $public = true;
62 * Whether the taxonomy is publicly queryable.
68 public $publicly_queryable = true;
71 * Whether the taxonomy is hierarchical.
77 public $hierarchical = false;
80 * Whether to generate and allow a UI for managing terms in this taxonomy in the admin.
86 public $show_ui = true;
89 * Whether to show the taxonomy in the admin menu.
91 * If true, the taxonomy is shown as a submenu of the object type menu. If false, no menu is shown.
97 public $show_in_menu = true;
100 * Whether the taxonomy is available for selection in navigation menus.
106 public $show_in_nav_menus = true;
109 * Whether to list the taxonomy in the tag cloud widget controls.
115 public $show_tagcloud = true;
118 * Whether to show the taxonomy in the quick/bulk edit panel.
124 public $show_in_quick_edit = true;
127 * Whether to display a column for the taxonomy on its post type listing screens.
133 public $show_admin_column = false;
136 * The callback function for the meta box display.
142 public $meta_box_cb = null;
145 * An array of object types this taxonomy is registered for.
151 public $object_type = null;
154 * Capabilities for this taxonomy.
163 * Rewrites information for this taxonomy.
172 * Query var string for this taxonomy.
181 * Function that will be called when the count is updated.
187 public $update_count_callback;
190 * Whether it is a built-in taxonomy.
204 * @global WP $wp WP instance.
206 * @param string $taxonomy Taxonomy key, must not exceed 32 characters.
207 * @param array|string $object_type Name of the object type for the taxonomy object.
208 * @param array|string $args Optional. Array or query string of arguments for registering a taxonomy.
209 * Default empty array.
211 public function __construct( $taxonomy, $object_type, $args = array() ) {
212 $this->name = $taxonomy;
214 $this->set_props( $object_type, $args );
218 * Sets taxonomy properties.
223 * @param array|string $object_type Name of the object type for the taxonomy object.
224 * @param array|string $args Array or query string of arguments for registering a taxonomy.
226 public function set_props( $object_type, $args ) {
227 $args = wp_parse_args( $args );
230 * Filters the arguments for registering a taxonomy.
234 * @param array $args Array of arguments for registering a taxonomy.
235 * @param string $taxonomy Taxonomy key.
236 * @param array $object_type Array of names of object types for the taxonomy.
238 $args = apply_filters( 'register_taxonomy_args', $args, $this->name, (array) $object_type );
244 'publicly_queryable' => null,
245 'hierarchical' => false,
247 'show_in_menu' => null,
248 'show_in_nav_menus' => null,
249 'show_tagcloud' => null,
250 'show_in_quick_edit' => null,
251 'show_admin_column' => false,
252 'meta_box_cb' => null,
253 'capabilities' => array(),
255 'query_var' => $this->name,
256 'update_count_callback' => '',
260 $args = array_merge( $defaults, $args );
262 // If not set, default to the setting for public.
263 if ( null === $args['publicly_queryable'] ) {
264 $args['publicly_queryable'] = $args['public'];
267 if ( false !== $args['query_var'] && ( is_admin() || false !== $args['publicly_queryable'] ) ) {
268 if ( true === $args['query_var'] ) {
269 $args['query_var'] = $this->name;
271 $args['query_var'] = sanitize_title_with_dashes( $args['query_var'] );
274 // Force query_var to false for non-public taxonomies.
275 $args['query_var'] = false;
278 if ( false !== $args['rewrite'] && ( is_admin() || '' != get_option( 'permalink_structure' ) ) ) {
279 $args['rewrite'] = wp_parse_args( $args['rewrite'], array(
280 'with_front' => true,
281 'hierarchical' => false,
282 'ep_mask' => EP_NONE,
285 if ( empty( $args['rewrite']['slug'] ) ) {
286 $args['rewrite']['slug'] = sanitize_title_with_dashes( $this->name );
290 // If not set, default to the setting for public.
291 if ( null === $args['show_ui'] ) {
292 $args['show_ui'] = $args['public'];
295 // If not set, default to the setting for show_ui.
296 if ( null === $args['show_in_menu'] || ! $args['show_ui'] ) {
297 $args['show_in_menu'] = $args['show_ui'];
300 // If not set, default to the setting for public.
301 if ( null === $args['show_in_nav_menus'] ) {
302 $args['show_in_nav_menus'] = $args['public'];
305 // If not set, default to the setting for show_ui.
306 if ( null === $args['show_tagcloud'] ) {
307 $args['show_tagcloud'] = $args['show_ui'];
310 // If not set, default to the setting for show_ui.
311 if ( null === $args['show_in_quick_edit'] ) {
312 $args['show_in_quick_edit'] = $args['show_ui'];
315 $default_caps = array(
316 'manage_terms' => 'manage_categories',
317 'edit_terms' => 'manage_categories',
318 'delete_terms' => 'manage_categories',
319 'assign_terms' => 'edit_posts',
322 $args['cap'] = (object) array_merge( $default_caps, $args['capabilities'] );
323 unset( $args['capabilities'] );
325 $args['object_type'] = array_unique( (array) $object_type );
327 // If not set, use the default meta box
328 if ( null === $args['meta_box_cb'] ) {
329 if ( $args['hierarchical'] ) {
330 $args['meta_box_cb'] = 'post_categories_meta_box';
332 $args['meta_box_cb'] = 'post_tags_meta_box';
336 foreach ( $args as $property_name => $property_value ) {
337 $this->$property_name = $property_value;
340 $this->labels = get_taxonomy_labels( $this );
341 $this->label = $this->labels->name;
345 * Adds the necessary rewrite rules for the taxonomy.
350 * @global WP $wp Current WordPress environment instance.
352 public function add_rewrite_rules() {
356 // Non-publicly queryable taxonomies should not register query vars, except in the admin.
357 if ( false !== $this->query_var && $wp ) {
358 $wp->add_query_var( $this->query_var );
361 if ( false !== $this->rewrite && ( is_admin() || '' != get_option( 'permalink_structure' ) ) ) {
362 if ( $this->hierarchical && $this->rewrite['hierarchical'] ) {
368 add_rewrite_tag( "%$this->name%", $tag, $this->query_var ? "{$this->query_var}=" : "taxonomy=$this->name&term=" );
369 add_permastruct( $this->name, "{$this->rewrite['slug']}/%$this->name%", $this->rewrite );
374 * Removes any rewrite rules, permastructs, and rules for the taxonomy.
379 * @global WP $wp Current WordPress environment instance.
381 public function remove_rewrite_rules() {
386 if ( false !== $this->query_var ) {
387 $wp->remove_query_var( $this->query_var );
390 // Remove rewrite tags and permastructs.
391 if ( false !== $this->rewrite ) {
392 remove_rewrite_tag( "%$this->name%" );
393 remove_permastruct( $this->name );
398 * Registers the ajax callback for the meta box.
403 public function add_hooks() {
404 add_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' );
408 * Removes the ajax callback for the meta box.
413 public function remove_hooks() {
414 remove_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' );