WordPress 4.7
[autoinstalls/wordpress.git] / 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 it is a built-in taxonomy.
191          *
192          * @since 4.7.0
193          * @access public
194          * @var bool
195          */
196         public $_builtin;
197
198         /**
199          * Constructor.
200          *
201          * @since 4.7.0
202          * @access public
203          *
204          * @global WP $wp WP instance.
205          *
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.
210          */
211         public function __construct( $taxonomy, $object_type, $args = array() ) {
212                 $this->name = $taxonomy;
213
214                 $this->set_props( $object_type, $args );
215         }
216
217         /**
218          * Sets taxonomy properties.
219          *
220          * @since 4.7.0
221          * @access public
222          *
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.
225          */
226         public function set_props( $object_type, $args ) {
227                 $args = wp_parse_args( $args );
228
229                 /**
230                  * Filters the arguments for registering a taxonomy.
231                  *
232                  * @since 4.4.0
233                  *
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.
237                  */
238                 $args = apply_filters( 'register_taxonomy_args', $args, $this->name, (array) $object_type );
239
240                 $defaults = array(
241                         'labels'                => array(),
242                         'description'           => '',
243                         'public'                => true,
244                         'publicly_queryable'    => null,
245                         'hierarchical'          => false,
246                         'show_ui'               => null,
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(),
254                         'rewrite'               => true,
255                         'query_var'             => $this->name,
256                         'update_count_callback' => '',
257                         '_builtin'              => false,
258                 );
259
260                 $args = array_merge( $defaults, $args );
261
262                 // If not set, default to the setting for public.
263                 if ( null === $args['publicly_queryable'] ) {
264                         $args['publicly_queryable'] = $args['public'];
265                 }
266
267                 if ( false !== $args['query_var'] && ( is_admin() || false !== $args['publicly_queryable'] ) ) {
268                         if ( true === $args['query_var'] ) {
269                                 $args['query_var'] = $this->name;
270                         } else {
271                                 $args['query_var'] = sanitize_title_with_dashes( $args['query_var'] );
272                         }
273                 } else {
274                         // Force query_var to false for non-public taxonomies.
275                         $args['query_var'] = false;
276                 }
277
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,
283                         ) );
284
285                         if ( empty( $args['rewrite']['slug'] ) ) {
286                                 $args['rewrite']['slug'] = sanitize_title_with_dashes( $this->name );
287                         }
288                 }
289
290                 // If not set, default to the setting for public.
291                 if ( null === $args['show_ui'] ) {
292                         $args['show_ui'] = $args['public'];
293                 }
294
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'];
298                 }
299
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'];
303                 }
304
305                 // If not set, default to the setting for show_ui.
306                 if ( null === $args['show_tagcloud'] ) {
307                         $args['show_tagcloud'] = $args['show_ui'];
308                 }
309
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'];
313                 }
314
315                 $default_caps = array(
316                         'manage_terms' => 'manage_categories',
317                         'edit_terms'   => 'manage_categories',
318                         'delete_terms' => 'manage_categories',
319                         'assign_terms' => 'edit_posts',
320                 );
321
322                 $args['cap'] = (object) array_merge( $default_caps, $args['capabilities'] );
323                 unset( $args['capabilities'] );
324
325                 $args['object_type'] = array_unique( (array) $object_type );
326
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';
331                         } else {
332                                 $args['meta_box_cb'] = 'post_tags_meta_box';
333                         }
334                 }
335
336                 foreach ( $args as $property_name => $property_value ) {
337                         $this->$property_name = $property_value;
338                 }
339
340                 $this->labels = get_taxonomy_labels( $this );
341                 $this->label = $this->labels->name;
342         }
343
344         /**
345          * Adds the necessary rewrite rules for the taxonomy.
346          *
347          * @since 4.7.0
348          * @access public
349          *
350          * @global WP $wp Current WordPress environment instance.
351          */
352         public function add_rewrite_rules() {
353                 /* @var WP $wp */
354                 global $wp;
355
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 );
359                 }
360
361                 if ( false !== $this->rewrite && ( is_admin() || '' != get_option( 'permalink_structure' ) ) ) {
362                         if ( $this->hierarchical && $this->rewrite['hierarchical'] ) {
363                                 $tag = '(.+?)';
364                         } else {
365                                 $tag = '([^/]+)';
366                         }
367
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 );
370                 }
371         }
372
373         /**
374          * Removes any rewrite rules, permastructs, and rules for the taxonomy.
375          *
376          * @since 4.7.0
377          * @access public
378          *
379          * @global WP $wp Current WordPress environment instance.
380          */
381         public function remove_rewrite_rules() {
382                 /* @var WP $wp */
383                 global $wp;
384
385                 // Remove query var.
386                 if ( false !== $this->query_var ) {
387                         $wp->remove_query_var( $this->query_var );
388                 }
389
390                 // Remove rewrite tags and permastructs.
391                 if ( false !== $this->rewrite ) {
392                         remove_rewrite_tag( "%$this->name%" );
393                         remove_permastruct( $this->name );
394                 }
395         }
396
397         /**
398          * Registers the ajax callback for the meta box.
399          *
400          * @since 4.7.0
401          * @access public
402          */
403         public function add_hooks() {
404                 add_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' );
405         }
406
407         /**
408          * Removes the ajax callback for the meta box.
409          *
410          * @since 4.7.0
411          * @access public
412          */
413         public function remove_hooks() {
414                 remove_filter( 'wp_ajax_add-' . $this->name, '_wp_ajax_add_hierarchical_term' );
415         }
416 }