register_taxonomy

Creates or modifies a taxonomy object.

Description

(WP_Error|void) register_taxonomy( (string) $taxonomy, (array|string) $object_type, (array) $args = array() ); 

Note: Do not use before the hook.

A simple function for creating or modifying a taxonomy object based on the parameters given. The function will accept an array (third optional parameter), along with strings for the taxonomy name and another string for the object type.

Returns (WP_Error|void)

WP_Error, if errors.

Parameters (3)

0. $taxonomy (string)
Taxonomy key, must not exceed 32 characters.
1. $object_type (array|string)
Object type or array of object types with which the taxonomy should be associated.
2. $args — Optional. (array) => array()
Array or query string of arguments for registering a taxonomy.

Options

  • labels (array) => 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().

  • description (string) => ''

    A short descriptive summary of what the taxonomy is for.

  • public (bool) => null

    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_queryable (bool) => null

    Whether the taxonomy is publicly queryable. If not set, the default is inherited from $public

  • hierarchical (bool) => false

    Whether the taxonomy is hierarchical.

  • show_ui (bool) => true

    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

  • show_in_menu (bool) => true

    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

  • show_in_nav_menus (bool) => true

    Makes this taxonomy available for selection in navigation menus. If not set, the default is inherited from $public

  • show_in_rest (bool) => null

    Whether to include the taxonomy in the REST API.

  • rest_base (string) => is $taxonomy

    To change the base url of REST API route.

  • rest_controller_class (string) => 'WP_REST_Terms_Controller'

    REST API Controller class name.

  • show_tagcloud (bool) => true

    Whether to list the taxonomy in the Tag Cloud Widget controls. If not set, the default is inherited from $show_ui

  • show_in_quick_edit (bool) => true

    Whether to show the taxonomy in the quick/bulk edit panel. It not set, the default is inherited from $show_ui

  • show_admin_column (bool) => false

    Whether to display a column for the taxonomy on its post type listing screens.

  • capabilities (array) => array()

    Array of capabilities for this taxonomy.

    • manage_terms (string) => 'manage_categories'
    • edit_terms (string) => 'manage_categories'
    • delete_terms (string) => 'manage_categories'
    • assign_terms (string) => 'edit_posts'
  • rewrite (bool|array) => array()

    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:

    • slug (string) => '$taxonomy key'

      Customize the permastruct slug.

    • with_front (bool) => true

      Should the permastruct be prepended with WP_Rewrite::$front.

    • hierarchical (bool) => false

      Either hierarchical rewrite tag or not.

    • ep_mask (int) => 'EP_NONE'

      Assign an endpoint mask.

  • meta_box_cb (bool|callable) => null

    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.

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().
     *
     * @type array
     * @default array()
     */
    'labels' => array(),

    /**
     * A short descriptive summary of what the taxonomy is for.
     *
     * @type string
     * @default ''
     */
    'description' => '',

    /**
     * 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`.
     *
     * @type bool
     * @default null
     */
    'public' => null,

    /**
     * Whether the taxonomy is publicly queryable. If not set, the default is inherited from
     * `$public`
     *
     * @type bool
     * @default null
     */
    'publicly_queryable' => null,

    /**
     * Whether the taxonomy is hierarchical.
     *
     * @type bool
     * @default false
     */
    'hierarchical' => false,

    /**
     * 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`
     *
     * @type bool
     * @default true
     */
    'show_ui' => true,

    /**
     * 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`
     *
     * @type bool
     * @default true
     */
    'show_in_menu' => true,

    /**
     * Makes this taxonomy available for selection in navigation menus. If not set, the default is
     * inherited from `$public`
     *
     * @type bool
     * @default true
     */
    'show_in_nav_menus' => true,

    /**
     * Whether to include the taxonomy in the REST API.
     *
     * @type bool
     * @default null
     */
    'show_in_rest' => null,

    /**
     * To change the base url of REST API route.
     *
     * @type string
     * @default is $taxonomy
     */
    'rest_base' => is $taxonomy,

    /**
     * REST API Controller class name.
     *
     * @type string
     * @default 'WP_REST_Terms_Controller'
     */
    'rest_controller_class' => 'WP_REST_Terms_Controller',

    /**
     * Whether to list the taxonomy in the Tag Cloud Widget controls. If not set, the default is
     * inherited from `$show_ui`
     *
     * @type bool
     * @default true
     */
    'show_tagcloud' => true,

    /**
     * Whether to show the taxonomy in the quick/bulk edit panel. It not set, the default is inherited
     * from `$show_ui`
     *
     * @type bool
     * @default true
     */
    'show_in_quick_edit' => true,

    /**
     * Whether to display a column for the taxonomy on its post type listing screens.
     *
     * @type bool
     * @default false
     */
    'show_admin_column' => false,

    /**
     * Array of capabilities for this taxonomy.
     *
     * @type array
     */
    'capabilities' => array(
        'manage_terms' => 'manage_categories',
        'edit_terms' => 'manage_categories',
        'delete_terms' => 'manage_categories',
        'assign_terms' => 'edit_posts'
    ),

    /**
     * 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 bool|array
     */
    'rewrite' => array(

        /**
         * Customize the permastruct slug.
         *
         * @type string
         * @default '$taxonomy key'
         */
        'slug' => '$taxonomy key',

        /**
         * Should the permastruct be prepended with WP_Rewrite::$front.
         *
         * @type bool
         * @default true
         */
        'with_front' => true,

        /**
         * Either hierarchical rewrite tag or not.
         *
         * @type bool
         * @default false
         */
        'hierarchical' => false,

        /**
         * Assign an endpoint mask.
         *
         * @type int
         * @default 'EP_NONE'
         */
        'ep_mask' => 'EP_NONE'
    ),

    /**
     * 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.
     *
     * @type bool|callable
     * @default null
     */
    'meta_box_cb' => null
);        


Usage

  1. if ( !function_exists( 'register_taxonomy' ) ) { 
  2. require_once ABSPATH . WPINC . '/taxonomy.php'; 
  3.  
  4. // Taxonomy key, must not exceed 32 characters. 
  5. $taxonomy = ''; 
  6.  
  7. // Object type or array of object types with which the taxonomy should be associated. 
  8. $object_type = null; 
  9.  
  10. // Optional. Array or query string of arguments for registering a taxonomy. 
  11. $args = array( 
  12. 'labels' => array(), 
  13. 'description' => '', 
  14. 'public' => null, 
  15. 'publicly_queryable' => null, 
  16. 'hierarchical' => false, 
  17. 'show_ui' => true, 
  18. 'show_in_menu' => true, 
  19. 'show_in_nav_menus' => true, 
  20. 'show_in_rest' => null, 
  21. 'rest_base' => is $taxonomy, 
  22. 'rest_controller_class' => 'WP_REST_Terms_Controller', 
  23. 'show_tagcloud' => true, 
  24. 'show_in_quick_edit' => true, 
  25. 'show_admin_column' => false, 
  26. 'capabilities' => array( 
  27. 'manage_terms' => 'manage_categories', 
  28. 'edit_terms' => 'manage_categories', 
  29. 'delete_terms' => 'manage_categories', 
  30. 'assign_terms' => 'edit_posts' 
  31. ), 
  32. 'rewrite' => array( 
  33. 'slug' => '$taxonomy key', 
  34. 'with_front' => true, 
  35. 'hierarchical' => false, 
  36. 'ep_mask' => 'EP_NONE' 
  37. ), 
  38. 'meta_box_cb' => null 
  39. ); 
  40.  
  41. // NOTICE! Understand what this does before running. 
  42. $result = register_taxonomy($taxonomy, $object_type, $args); 
  43.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/taxonomy.php  
  1. function register_taxonomy( $taxonomy, $object_type, $args = array() ) { 
  2. global $wp_taxonomies; 
  3.  
  4. if ( ! is_array( $wp_taxonomies ) ) 
  5. $wp_taxonomies = array(); 
  6.  
  7. $args = wp_parse_args( $args ); 
  8.  
  9. if ( empty( $taxonomy ) || strlen( $taxonomy ) > 32 ) { 
  10. _doing_it_wrong( __FUNCTION__, __( 'Taxonomy names must be between 1 and 32 characters in length.' ), '4.2.0' ); 
  11. return new WP_Error( 'taxonomy_length_invalid', __( 'Taxonomy names must be between 1 and 32 characters in length.' ) ); 
  12.  
  13. $taxonomy_object = new WP_Taxonomy( $taxonomy, $object_type, $args ); 
  14. $taxonomy_object->add_rewrite_rules(); 
  15.  
  16. $wp_taxonomies[ $taxonomy ] = $taxonomy_object; 
  17.  
  18. $taxonomy_object->add_hooks(); 
  19.  
  20.  
  21. /** 
  22. * Fires after a taxonomy is registered. 
  23. * @since 3.3.0 
  24. * @param string $taxonomy Taxonomy slug. 
  25. * @param array|string $object_type Object type or array of object types. 
  26. * @param array $args Array of taxonomy registration arguments. 
  27. */ 
  28. do_action( 'registered_taxonomy', $taxonomy, $object_type, (array) $taxonomy_object );