/wp-includes/class-wp-taxonomy.php

  1. <?php 
  2. /** 
  3. * Taxonomy API: WP_Taxonomy class 
  4. * 
  5. * @package WordPress 
  6. * @subpackage Taxonomy 
  7. * @since 4.7.0 
  8. */ 
  9.  
  10. /** 
  11. * Core class used for interacting with taxonomies. 
  12. * 
  13. * @since 4.7.0 
  14. */ 
  15. final class WP_Taxonomy { 
  16. /** 
  17. * Taxonomy key. 
  18. * 
  19. * @since 4.7.0 
  20. * @access public 
  21. * @var string 
  22. */ 
  23. public $name; 
  24.  
  25. /** 
  26. * Name of the taxonomy shown in the menu. Usually plural. 
  27. * 
  28. * @since 4.7.0 
  29. * @access public 
  30. * @var string 
  31. */ 
  32. public $label; 
  33.  
  34. /** 
  35. * An array of labels for this taxonomy. 
  36. * 
  37. * @since 4.7.0 
  38. * @access public 
  39. * @var object 
  40. */ 
  41. public $labels = array(); 
  42.  
  43. /** 
  44. * A short descriptive summary of what the taxonomy is for. 
  45. * 
  46. * @since 4.7.0 
  47. * @access public 
  48. * @var string 
  49. */ 
  50. public $description = ''; 
  51.  
  52. /** 
  53. * Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users. 
  54. * 
  55. * @since 4.7.0 
  56. * @access public 
  57. * @var bool 
  58. */ 
  59. public $public = true; 
  60.  
  61. /** 
  62. * Whether the taxonomy is publicly queryable. 
  63. * 
  64. * @since 4.7.0 
  65. * @access public 
  66. * @var bool 
  67. */ 
  68. public $publicly_queryable = true; 
  69.  
  70. /** 
  71. * Whether the taxonomy is hierarchical. 
  72. * 
  73. * @since 4.7.0 
  74. * @access public 
  75. * @var bool 
  76. */ 
  77. public $hierarchical = false; 
  78.  
  79. /** 
  80. * Whether to generate and allow a UI for managing terms in this taxonomy in the admin. 
  81. * 
  82. * @since 4.7.0 
  83. * @access public 
  84. * @var bool 
  85. */ 
  86. public $show_ui = true; 
  87.  
  88. /** 
  89. * Whether to show the taxonomy in the admin menu. 
  90. * 
  91. * If true, the taxonomy is shown as a submenu of the object type menu. If false, no menu is shown. 
  92. * 
  93. * @since 4.7.0 
  94. * @access public 
  95. * @var bool 
  96. */ 
  97. public $show_in_menu = true; 
  98.  
  99. /** 
  100. * Whether the taxonomy is available for selection in navigation menus. 
  101. * 
  102. * @since 4.7.0 
  103. * @access public 
  104. * @var bool 
  105. */ 
  106. public $show_in_nav_menus = true; 
  107.  
  108. /** 
  109. * Whether to list the taxonomy in the tag cloud widget controls. 
  110. * 
  111. * @since 4.7.0 
  112. * @access public 
  113. * @var bool 
  114. */ 
  115. public $show_tagcloud = true; 
  116.  
  117. /** 
  118. * Whether to show the taxonomy in the quick/bulk edit panel. 
  119. * 
  120. * @since 4.7.0 
  121. * @access public 
  122. * @var bool 
  123. */ 
  124. public $show_in_quick_edit = true; 
  125.  
  126. /** 
  127. * Whether to display a column for the taxonomy on its post type listing screens. 
  128. * 
  129. * @since 4.7.0 
  130. * @access public 
  131. * @var bool 
  132. */ 
  133. public $show_admin_column = false; 
  134.  
  135. /** 
  136. * The callback function for the meta box display. 
  137. * 
  138. * @since 4.7.0 
  139. * @access public 
  140. * @var bool|callable 
  141. */ 
  142. public $meta_box_cb = null; 
  143.  
  144. /** 
  145. * An array of object types this taxonomy is registered for. 
  146. * 
  147. * @since 4.7.0 
  148. * @access public 
  149. * @var array 
  150. */ 
  151. public $object_type = null; 
  152.  
  153. /** 
  154. * Capabilities for this taxonomy. 
  155. * 
  156. * @since 4.7.0 
  157. * @access public 
  158. * @var array 
  159. */ 
  160. public $cap; 
  161.  
  162. /** 
  163. * Rewrites information for this taxonomy. 
  164. * 
  165. * @since 4.7.0 
  166. * @access public 
  167. * @var array|false 
  168. */ 
  169. public $rewrite; 
  170.  
  171. /** 
  172. * Query var string for this taxonomy. 
  173. * 
  174. * @since 4.7.0 
  175. * @access public 
  176. * @var string|false 
  177. */ 
  178. public $query_var; 
  179.  
  180. /** 
  181. * Function that will be called when the count is updated. 
  182. * 
  183. * @since 4.7.0 
  184. * @access public 
  185. * @var callable 
  186. */ 
  187. public $update_count_callback; 
  188.  
  189. /** 
  190. * Whether this taxonomy should appear in the REST API. 
  191. * 
  192. * Default false. If true, standard endpoints will be registered with 
  193. * respect to $rest_base and $rest_controller_class. 
  194. * 
  195. * @since 4.7.4 
  196. * @access public 
  197. * @var bool $show_in_rest 
  198. */ 
  199. public $show_in_rest; 
  200.  
  201. /** 
  202. * The base path for this taxonomy's REST API endpoints. 
  203. * 
  204. * @since 4.7.4 
  205. * @access public 
  206. * @var string|bool $rest_base 
  207. */ 
  208. public $rest_base; 
  209.  
  210. /** 
  211. * The controller for this taxonomy's REST API endpoints. 
  212. * 
  213. * Custom controllers must extend WP_REST_Controller. 
  214. * 
  215. * @since 4.7.4 
  216. * @access public 
  217. * @var string|bool $rest_controller_class 
  218. */ 
  219. public $rest_controller_class; 
  220.  
  221. /** 
  222. * Whether it is a built-in taxonomy. 
  223. * 
  224. * @since 4.7.0 
  225. * @access public 
  226. * @var bool 
  227. */ 
  228. public $_builtin; 
  229.  
  230. /** 
  231. * Constructor. 
  232. * 
  233. * @since 4.7.0 
  234. * @access public 
  235. * 
  236. * @global WP $wp WP instance. 
  237. * 
  238. * @param string $taxonomy Taxonomy key, must not exceed 32 characters. 
  239. * @param array|string $object_type Name of the object type for the taxonomy object. 
  240. * @param array|string $args Optional. Array or query string of arguments for registering a taxonomy. 
  241. * Default empty array. 
  242. */ 
  243. public function __construct( $taxonomy, $object_type, $args = array() ) { 
  244. $this->name = $taxonomy; 
  245.  
  246. $this->set_props( $object_type, $args ); 
  247.  
  248. /** 
  249. * Sets taxonomy properties. 
  250. * 
  251. * @since 4.7.0 
  252. * @access public 
  253. * 
  254. * @param array|string $object_type Name of the object type for the taxonomy object. 
  255. * @param array|string $args Array or query string of arguments for registering a taxonomy. 
  256. */ 
  257. public function set_props( $object_type, $args ) { 
  258. $args = wp_parse_args( $args ); 
  259.  
  260. /** 
  261. * Filters the arguments for registering a taxonomy. 
  262. * 
  263. * @since 4.4.0 
  264. * 
  265. * @param array $args Array of arguments for registering a taxonomy. 
  266. * @param string $taxonomy Taxonomy key. 
  267. * @param array $object_type Array of names of object types for the taxonomy. 
  268. */ 
  269. $args = apply_filters( 'register_taxonomy_args', $args, $this->name, (array) $object_type ); 
  270.  
  271. $defaults = array( 
  272. 'labels' => array(),  
  273. 'description' => '',  
  274. 'public' => true,  
  275. 'publicly_queryable' => null,  
  276. 'hierarchical' => false,  
  277. 'show_ui' => null,  
  278. 'show_in_menu' => null,  
  279. 'show_in_nav_menus' => null,  
  280. 'show_tagcloud' => null,  
  281. 'show_in_quick_edit' => null,  
  282. 'show_admin_column' => false,  
  283. 'meta_box_cb' => null,  
  284. 'capabilities' => array(),  
  285. 'rewrite' => true,  
  286. 'query_var' => $this->name,  
  287. 'update_count_callback' => '',  
  288. 'show_in_rest' => false,  
  289. 'rest_base' => false,  
  290. 'rest_controller_class' => false,  
  291. '_builtin' => false,  
  292. ); 
  293.  
  294. $args = array_merge( $defaults, $args ); 
  295.  
  296. // If not set, default to the setting for public. 
  297. if ( null === $args['publicly_queryable'] ) { 
  298. $args['publicly_queryable'] = $args['public']; 
  299.  
  300. if ( false !== $args['query_var'] && ( is_admin() || false !== $args['publicly_queryable'] ) ) { 
  301. if ( true === $args['query_var'] ) { 
  302. $args['query_var'] = $this->name; 
  303. } else { 
  304. $args['query_var'] = sanitize_title_with_dashes( $args['query_var'] ); 
  305. } else { 
  306. // Force query_var to false for non-public taxonomies. 
  307. $args['query_var'] = false; 
  308.  
  309. if ( false !== $args['rewrite'] && ( is_admin() || '' != get_option( 'permalink_structure' ) ) ) { 
  310. $args['rewrite'] = wp_parse_args( $args['rewrite'], array( 
  311. 'with_front' => true,  
  312. 'hierarchical' => false,  
  313. 'ep_mask' => EP_NONE,  
  314. ) ); 
  315.  
  316. if ( empty( $args['rewrite']['slug'] ) ) { 
  317. $args['rewrite']['slug'] = sanitize_title_with_dashes( $this->name ); 
  318.  
  319. // If not set, default to the setting for public. 
  320. if ( null === $args['show_ui'] ) { 
  321. $args['show_ui'] = $args['public']; 
  322.  
  323. // If not set, default to the setting for show_ui. 
  324. if ( null === $args['show_in_menu'] || ! $args['show_ui'] ) { 
  325. $args['show_in_menu'] = $args['show_ui']; 
  326.  
  327. // If not set, default to the setting for public. 
  328. if ( null === $args['show_in_nav_menus'] ) { 
  329. $args['show_in_nav_menus'] = $args['public']; 
  330.  
  331. // If not set, default to the setting for show_ui. 
  332. if ( null === $args['show_tagcloud'] ) { 
  333. $args['show_tagcloud'] = $args['show_ui']; 
  334.  
  335. // If not set, default to the setting for show_ui. 
  336. if ( null === $args['show_in_quick_edit'] ) { 
  337. $args['show_in_quick_edit'] = $args['show_ui']; 
  338.  
  339. $default_caps = array( 
  340. 'manage_terms' => 'manage_categories',  
  341. 'edit_terms' => 'manage_categories',  
  342. 'delete_terms' => 'manage_categories',  
  343. 'assign_terms' => 'edit_posts',  
  344. ); 
  345.  
  346. $args['cap'] = (object) array_merge( $default_caps, $args['capabilities'] ); 
  347. unset( $args['capabilities'] ); 
  348.  
  349. $args['object_type'] = array_unique( (array) $object_type ); 
  350.  
  351. // If not set, use the default meta box 
  352. if ( null === $args['meta_box_cb'] ) { 
  353. if ( $args['hierarchical'] ) { 
  354. $args['meta_box_cb'] = 'post_categories_meta_box'; 
  355. } else { 
  356. $args['meta_box_cb'] = 'post_tags_meta_box'; 
  357.  
  358. $args['name'] = $this->name; 
  359.  
  360. foreach ( $args as $property_name => $property_value ) { 
  361. $this->$property_name = $property_value; 
  362.  
  363. $this->labels = get_taxonomy_labels( $this ); 
  364. $this->label = $this->labels->name; 
  365.  
  366. /** 
  367. * Adds the necessary rewrite rules for the taxonomy. 
  368. * 
  369. * @since 4.7.0 
  370. * @access public 
  371. * 
  372. * @global WP $wp Current WordPress environment instance. 
  373. */ 
  374. public function add_rewrite_rules() { 
  375. /** @var WP $wp */ 
  376. global $wp; 
  377.  
  378. // Non-publicly queryable taxonomies should not register query vars, except in the admin. 
  379. if ( false !== $this->query_var && $wp ) { 
  380. $wp->add_query_var( $this->query_var ); 
  381.  
  382. if ( false !== $this->rewrite && ( is_admin() || '' != get_option( 'permalink_structure' ) ) ) { 
  383. if ( $this->hierarchical && $this->rewrite['hierarchical'] ) { 
  384. $tag = '(.+?)'; 
  385. } else { 
  386. $tag = '([^/]+)'; 
  387.  
  388. add_rewrite_tag( "%$this->name%", $tag, $this->query_var ? "{$this->query_var}=" : "taxonomy=$this->name&term=" ); 
  389. add_permastruct( $this->name, "{$this->rewrite['slug']}/%$this->name%", $this->rewrite ); 
  390.  
  391. /** 
  392. * Removes any rewrite rules, permastructs, and rules for the taxonomy. 
  393. * 
  394. * @since 4.7.0 
  395. * @access public 
  396. * 
  397. * @global WP $wp Current WordPress environment instance. 
  398. */ 
  399. public function remove_rewrite_rules() { 
  400. /** @var WP $wp */ 
  401. global $wp; 
  402.  
  403. // Remove query var. 
  404. if ( false !== $this->query_var ) { 
  405. $wp->remove_query_var( $this->query_var ); 
  406.  
  407. // Remove rewrite tags and permastructs. 
  408. if ( false !== $this->rewrite ) { 
  409. remove_rewrite_tag( "%$this->name%" ); 
  410. remove_permastruct( $this->name ); 
  411.  
  412. /** 
  413. * Registers the ajax callback for the meta box. 
  414. * 
  415. * @since 4.7.0 
  416. * @access public 
  417. */ 
  418. public function add_hooks() { 
  419. add_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' ); 
  420.  
  421. /** 
  422. * Removes the ajax callback for the meta box. 
  423. * 
  424. * @since 4.7.0 
  425. * @access public 
  426. */ 
  427. public function remove_hooks() { 
  428. remove_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' ); 
.