forked from WordPress/WordPress
/
taxonomy.php
3294 lines (2862 loc) · 107 KB
/
taxonomy.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?php
/**
* Taxonomy API
*
* @package WordPress
* @subpackage Taxonomy
* @since 2.3.0
*/
//
// Taxonomy Registration
//
/**
* Creates the initial taxonomies.
*
* This function fires twice: in wp-settings.php before plugins are loaded (for
* backwards compatibility reasons), and again on the 'init' action. We must avoid
* registering rewrite rules before the 'init' action.
*/
function create_initial_taxonomies() {
global $wp_rewrite;
if ( ! did_action( 'init' ) ) {
$rewrite = array( 'category' => false, 'post_tag' => false, 'post_format' => false );
} else {
$post_format_base = apply_filters( 'post_format_rewrite_base', 'type' );
$rewrite = array(
'category' => array(
'hierarchical' => true,
'slug' => get_option('category_base') ? get_option('category_base') : 'category',
'with_front' => ! get_option('category_base') || $wp_rewrite->using_index_permalinks(),
'ep_mask' => EP_CATEGORIES,
),
'post_tag' => array(
'slug' => get_option('tag_base') ? get_option('tag_base') : 'tag',
'with_front' => ! get_option('tag_base') || $wp_rewrite->using_index_permalinks(),
'ep_mask' => EP_TAGS,
),
'post_format' => $post_format_base ? array( 'slug' => $post_format_base ) : false,
);
}
register_taxonomy( 'category', 'post', array(
'hierarchical' => true,
'query_var' => 'category_name',
'rewrite' => $rewrite['category'],
'public' => true,
'show_ui' => true,
'show_admin_column' => true,
'_builtin' => true,
) );
register_taxonomy( 'post_tag', 'post', array(
'hierarchical' => false,
'query_var' => 'tag',
'rewrite' => $rewrite['post_tag'],
'public' => true,
'show_ui' => true,
'show_admin_column' => true,
'_builtin' => true,
) );
register_taxonomy( 'nav_menu', 'nav_menu_item', array(
'public' => false,
'hierarchical' => false,
'labels' => array(
'name' => __( 'Navigation Menus' ),
'singular_name' => __( 'Navigation Menu' ),
),
'query_var' => false,
'rewrite' => false,
'show_ui' => false,
'_builtin' => true,
'show_in_nav_menus' => false,
) );
register_taxonomy( 'link_category', 'link', array(
'hierarchical' => false,
'labels' => array(
'name' => __( 'Link Categories' ),
'singular_name' => __( 'Link Category' ),
'search_items' => __( 'Search Link Categories' ),
'popular_items' => null,
'all_items' => __( 'All Link Categories' ),
'edit_item' => __( 'Edit Link Category' ),
'update_item' => __( 'Update Link Category' ),
'add_new_item' => __( 'Add New Link Category' ),
'new_item_name' => __( 'New Link Category Name' ),
'separate_items_with_commas' => null,
'add_or_remove_items' => null,
'choose_from_most_used' => null,
),
'capabilities' => array(
'manage_terms' => 'manage_links',
'edit_terms' => 'manage_links',
'delete_terms' => 'manage_links',
'assign_terms' => 'manage_links',
),
'query_var' => false,
'rewrite' => false,
'public' => false,
'show_ui' => false,
'_builtin' => true,
) );
register_taxonomy( 'post_format', 'post', array(
'public' => true,
'hierarchical' => false,
'labels' => array(
'name' => _x( 'Format', 'post format' ),
'singular_name' => _x( 'Format', 'post format' ),
),
'query_var' => true,
'rewrite' => $rewrite['post_format'],
'show_ui' => false,
'_builtin' => true,
'show_in_nav_menus' => current_theme_supports( 'post-formats' ),
) );
}
add_action( 'init', 'create_initial_taxonomies', 0 ); // highest priority
/**
* Get a list of registered taxonomy objects.
*
* @package WordPress
* @subpackage Taxonomy
* @since 3.0.0
* @uses $wp_taxonomies
* @see register_taxonomy
*
* @param array $args An array of key => value arguments to match against the taxonomy objects.
* @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
* @param string $operator The logical operation to perform. 'or' means only one element
* from the array needs to match; 'and' means all elements must match. The default is 'and'.
* @return array A list of taxonomy names or objects
*/
function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' ) {
global $wp_taxonomies;
$field = ('names' == $output) ? 'name' : false;
return wp_filter_object_list($wp_taxonomies, $args, $operator, $field);
}
/**
* Return all of the taxonomy names that are of $object_type.
*
* It appears that this function can be used to find all of the names inside of
* $wp_taxonomies global variable.
*
* <code><?php $taxonomies = get_object_taxonomies('post'); ?></code> Should
* result in <code>Array('category', 'post_tag')</code>
*
* @package WordPress
* @subpackage Taxonomy
* @since 2.3.0
*
* @uses $wp_taxonomies
*
* @param array|string|object $object Name of the type of taxonomy object, or an object (row from posts)
* @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
* @return array The names of all taxonomy of $object_type.
*/
function get_object_taxonomies($object, $output = 'names') {
global $wp_taxonomies;
if ( is_object($object) ) {
if ( $object->post_type == 'attachment' )
return get_attachment_taxonomies($object);
$object = $object->post_type;
}
$object = (array) $object;
$taxonomies = array();
foreach ( (array) $wp_taxonomies as $tax_name => $tax_obj ) {
if ( array_intersect($object, (array) $tax_obj->object_type) ) {
if ( 'names' == $output )
$taxonomies[] = $tax_name;
else
$taxonomies[ $tax_name ] = $tax_obj;
}
}
return $taxonomies;
}
/**
* Retrieves the taxonomy object of $taxonomy.
*
* The get_taxonomy function will first check that the parameter string given
* is a taxonomy object and if it is, it will return it.
*
* @package WordPress
* @subpackage Taxonomy
* @since 2.3.0
*
* @uses $wp_taxonomies
* @uses taxonomy_exists() Checks whether taxonomy exists
*
* @param string $taxonomy Name of taxonomy object to return
* @return object|bool The Taxonomy Object or false if $taxonomy doesn't exist
*/
function get_taxonomy( $taxonomy ) {
global $wp_taxonomies;
if ( ! taxonomy_exists( $taxonomy ) )
return false;
return $wp_taxonomies[$taxonomy];
}
/**
* Checks that the taxonomy name exists.
*
* Formerly is_taxonomy(), introduced in 2.3.0.
*
* @package WordPress
* @subpackage Taxonomy
* @since 3.0.0
*
* @uses $wp_taxonomies
*
* @param string $taxonomy Name of taxonomy object
* @return bool Whether the taxonomy exists.
*/
function taxonomy_exists( $taxonomy ) {
global $wp_taxonomies;
return isset( $wp_taxonomies[$taxonomy] );
}
/**
* Whether the taxonomy object is hierarchical.
*
* Checks to make sure that the taxonomy is an object first. Then Gets the
* object, and finally returns the hierarchical value in the object.
*
* A false return value might also mean that the taxonomy does not exist.
*
* @package WordPress
* @subpackage Taxonomy
* @since 2.3.0
*
* @uses taxonomy_exists() Checks whether taxonomy exists
* @uses get_taxonomy() Used to get the taxonomy object
*
* @param string $taxonomy Name of taxonomy object
* @return bool Whether the taxonomy is hierarchical
*/
function is_taxonomy_hierarchical($taxonomy) {
if ( ! taxonomy_exists($taxonomy) )
return false;
$taxonomy = get_taxonomy($taxonomy);
return $taxonomy->hierarchical;
}
/**
* Create or modify a taxonomy object. Do not use before init.
*
* 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.
*
* Nothing is returned, so expect error maybe or use taxonomy_exists() to check
* whether taxonomy exists.
*
* Optional $args contents:
*
* label - Name of the taxonomy shown in the menu. Usually plural. If not set, labels['name'] will be used.
*
* hierarchical - has some defined purpose at other parts of the API and is a
* boolean value.
*
* update_count_callback - works much like a hook, in that it will be called when the count is updated.
* Defaults to _update_post_term_count() for taxonomies attached to post types, which then confirms
* that the objects are published before counting them.
* Defaults to _update_generic_term_count() for taxonomies attached to other object types, such as links.
*
* rewrite - false to prevent rewrite, or array('slug'=>$slug) to customize
* permastruct; default will use $taxonomy as slug.
*
* query_var - false to prevent queries, or string to customize query var
* (?$query_var=$term); default will use $taxonomy as query var.
*
* public - If the taxonomy should be publicly queryable; //@TODO not implemented.
* defaults to true.
*
* show_ui - If the WordPress UI admin tags UI should apply to this taxonomy;
* defaults to public.
*
* show_in_nav_menus - true makes this taxonomy available for selection in navigation menus.
* Defaults to public.
*
* show_tagcloud - false to prevent the taxonomy being listed in the Tag Cloud Widget;
* defaults to show_ui which defaults to public.
*
* labels - An array of labels for this taxonomy. You can see accepted values in {@link get_taxonomy_labels()}. By default tag labels are used for non-hierarchical types and category labels for hierarchical ones.
*
* @package WordPress
* @subpackage Taxonomy
* @since 2.3.0
* @uses $wp_taxonomies Inserts new taxonomy object into the list
* @uses $wp Adds query vars
*
* @param string $taxonomy Name of taxonomy object
* @param array|string $object_type Name of the object type for the taxonomy object.
* @param array|string $args See above description for the two keys values.
*/
function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
global $wp_taxonomies, $wp;
if ( ! is_array($wp_taxonomies) )
$wp_taxonomies = array();
$defaults = array( 'hierarchical' => false,
'update_count_callback' => '',
'rewrite' => true,
'query_var' => $taxonomy,
'public' => true,
'show_ui' => null,
'show_tagcloud' => null,
'_builtin' => false,
'labels' => array(),
'capabilities' => array(),
'show_in_nav_menus' => null,
);
$args = wp_parse_args($args, $defaults);
if ( false !== $args['query_var'] && !empty($wp) ) {
if ( true === $args['query_var'] )
$args['query_var'] = $taxonomy;
else
$args['query_var'] = sanitize_title_with_dashes($args['query_var']);
$wp->add_query_var($args['query_var']);
}
if ( false !== $args['rewrite'] && ( is_admin() || '' != get_option('permalink_structure') ) ) {
$args['rewrite'] = wp_parse_args($args['rewrite'], array(
'slug' => sanitize_title_with_dashes($taxonomy),
'with_front' => true,
'hierarchical' => false,
'ep_mask' => EP_NONE,
));
if ( $args['hierarchical'] && $args['rewrite']['hierarchical'] )
$tag = '(.+?)';
else
$tag = '([^/]+)';
add_rewrite_tag( "%$taxonomy%", $tag, $args['query_var'] ? "{$args['query_var']}=" : "taxonomy=$taxonomy&term=" );
add_permastruct( $taxonomy, "{$args['rewrite']['slug']}/%$taxonomy%", $args['rewrite'] );
}
if ( is_null($args['show_ui']) )
$args['show_ui'] = $args['public'];
// Whether to show this type in nav-menus.php. Defaults to the setting for public.
if ( null === $args['show_in_nav_menus'] )
$args['show_in_nav_menus'] = $args['public'];
if ( is_null($args['show_tagcloud']) )
$args['show_tagcloud'] = $args['show_ui'];
$default_caps = array(
'manage_terms' => 'manage_categories',
'edit_terms' => 'manage_categories',
'delete_terms' => 'manage_categories',
'assign_terms' => 'edit_posts',
);
$args['cap'] = (object) array_merge( $default_caps, $args['capabilities'] );
unset( $args['capabilities'] );
$args['name'] = $taxonomy;
$args['object_type'] = array_unique( (array)$object_type );
$args['labels'] = get_taxonomy_labels( (object) $args );
$args['label'] = $args['labels']->name;
$wp_taxonomies[$taxonomy] = (object) $args;
// register callback handling for metabox
add_filter('wp_ajax_add-' . $taxonomy, '_wp_ajax_add_hierarchical_term');
do_action( 'registered_taxonomy', $taxonomy, $object_type, $args );
}
/**
* Builds an object with all taxonomy labels out of a taxonomy object
*
* Accepted keys of the label array in the taxonomy object:
* - name - general name for the taxonomy, usually plural. The same as and overridden by $tax->label. Default is Tags/Categories
* - singular_name - name for one object of this taxonomy. Default is Tag/Category
* - search_items - Default is Search Tags/Search Categories
* - popular_items - This string isn't used on hierarchical taxonomies. Default is Popular Tags
* - all_items - Default is All Tags/All Categories
* - parent_item - This string isn't used on non-hierarchical taxonomies. In hierarchical ones the default is Parent Category
* - parent_item_colon - The same as <code>parent_item</code>, but with colon <code>:</code> in the end
* - edit_item - Default is Edit Tag/Edit Category
* - view_item - Default is View Tag/View Category
* - update_item - Default is Update Tag/Update Category
* - add_new_item - Default is Add New Tag/Add New Category
* - new_item_name - Default is New Tag Name/New Category Name
* - separate_items_with_commas - This string isn't used on hierarchical taxonomies. Default is "Separate tags with commas", used in the meta box.
* - add_or_remove_items - This string isn't used on hierarchical taxonomies. Default is "Add or remove tags", used in the meta box when JavaScript is disabled.
* - choose_from_most_used - This string isn't used on hierarchical taxonomies. Default is "Choose from the most used tags", used in the meta box.
*
* Above, the first default value is for non-hierarchical taxonomies (like tags) and the second one is for hierarchical taxonomies (like categories).
*
* @since 3.0.0
* @param object $tax Taxonomy object
* @return object object with all the labels as member variables
*/
function get_taxonomy_labels( $tax ) {
if ( isset( $tax->helps ) && empty( $tax->labels['separate_items_with_commas'] ) )
$tax->labels['separate_items_with_commas'] = $tax->helps;
$nohier_vs_hier_defaults = array(
'name' => array( _x( 'Tags', 'taxonomy general name' ), _x( 'Categories', 'taxonomy general name' ) ),
'singular_name' => array( _x( 'Tag', 'taxonomy singular name' ), _x( 'Category', 'taxonomy singular name' ) ),
'search_items' => array( __( 'Search Tags' ), __( 'Search Categories' ) ),
'popular_items' => array( __( 'Popular Tags' ), null ),
'all_items' => array( __( 'All Tags' ), __( 'All Categories' ) ),
'parent_item' => array( null, __( 'Parent Category' ) ),
'parent_item_colon' => array( null, __( 'Parent Category:' ) ),
'edit_item' => array( __( 'Edit Tag' ), __( 'Edit Category' ) ),
'view_item' => array( __( 'View Tag' ), __( 'View Category' ) ),
'update_item' => array( __( 'Update Tag' ), __( 'Update Category' ) ),
'add_new_item' => array( __( 'Add New Tag' ), __( 'Add New Category' ) ),
'new_item_name' => array( __( 'New Tag Name' ), __( 'New Category Name' ) ),
'separate_items_with_commas' => array( __( 'Separate tags with commas' ), null ),
'add_or_remove_items' => array( __( 'Add or remove tags' ), null ),
'choose_from_most_used' => array( __( 'Choose from the most used tags' ), null ),
);
$nohier_vs_hier_defaults['menu_name'] = $nohier_vs_hier_defaults['name'];
return _get_custom_object_labels( $tax, $nohier_vs_hier_defaults );
}
/**
* Add an already registered taxonomy to an object type.
*
* @package WordPress
* @subpackage Taxonomy
* @since 3.0.0
* @uses $wp_taxonomies Modifies taxonomy object
*
* @param string $taxonomy Name of taxonomy object
* @param string $object_type Name of the object type
* @return bool True if successful, false if not
*/
function register_taxonomy_for_object_type( $taxonomy, $object_type) {
global $wp_taxonomies;
if ( !isset($wp_taxonomies[$taxonomy]) )
return false;
if ( ! get_post_type_object($object_type) )
return false;
if ( ! in_array( $object_type, $wp_taxonomies[$taxonomy]->object_type ) )
$wp_taxonomies[$taxonomy]->object_type[] = $object_type;
return true;
}
//
// Term API
//
/**
* Retrieve object_ids of valid taxonomy and term.
*
* The strings of $taxonomies must exist before this function will continue. On
* failure of finding a valid taxonomy, it will return an WP_Error class, kind
* of like Exceptions in PHP 5, except you can't catch them. Even so, you can
* still test for the WP_Error class and get the error message.
*
* The $terms aren't checked the same as $taxonomies, but still need to exist
* for $object_ids to be returned.
*
* It is possible to change the order that object_ids is returned by either
* using PHP sort family functions or using the database by using $args with
* either ASC or DESC array. The value should be in the key named 'order'.
*
* @package WordPress
* @subpackage Taxonomy
* @since 2.3.0
*
* @uses $wpdb
* @uses wp_parse_args() Creates an array from string $args.
*
* @param int|array $term_ids Term id or array of term ids of terms that will be used
* @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names
* @param array|string $args Change the order of the object_ids, either ASC or DESC
* @return WP_Error|array If the taxonomy does not exist, then WP_Error will be returned. On success
* the array can be empty meaning that there are no $object_ids found or it will return the $object_ids found.
*/
function get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
global $wpdb;
if ( ! is_array( $term_ids ) )
$term_ids = array( $term_ids );
if ( ! is_array( $taxonomies ) )
$taxonomies = array( $taxonomies );
foreach ( (array) $taxonomies as $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) )
return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) );
}
$defaults = array( 'order' => 'ASC' );
$args = wp_parse_args( $args, $defaults );
extract( $args, EXTR_SKIP );
$order = ( 'desc' == strtolower( $order ) ) ? 'DESC' : 'ASC';
$term_ids = array_map('intval', $term_ids );
$taxonomies = "'" . implode( "', '", $taxonomies ) . "'";
$term_ids = "'" . implode( "', '", $term_ids ) . "'";
$object_ids = $wpdb->get_col("SELECT tr.object_id FROM $wpdb->term_relationships AS tr INNER JOIN $wpdb->term_taxonomy AS tt ON tr.term_taxonomy_id = tt.term_taxonomy_id WHERE tt.taxonomy IN ($taxonomies) AND tt.term_id IN ($term_ids) ORDER BY tr.object_id $order");
if ( ! $object_ids )
return array();
return $object_ids;
}
/**
* Given a taxonomy query, generates SQL to be appended to a main query.
*
* @since 3.1.0
*
* @see WP_Tax_Query
*
* @param array $tax_query A compact tax query
* @param string $primary_table
* @param string $primary_id_column
* @return array
*/
function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
$tax_query_obj = new WP_Tax_Query( $tax_query );
return $tax_query_obj->get_sql( $primary_table, $primary_id_column );
}
/**
* Container class for a multiple taxonomy query.
*
* @since 3.1.0
*/
class WP_Tax_Query {
/**
* List of taxonomy queries. A single taxonomy query is an associative array:
* - 'taxonomy' string The taxonomy being queried
* - 'terms' string|array The list of terms
* - 'field' string (optional) Which term field is being used.
* Possible values: 'term_id', 'slug' or 'name'
* Default: 'term_id'
* - 'operator' string (optional)
* Possible values: 'AND', 'IN' or 'NOT IN'.
* Default: 'IN'
* - 'include_children' bool (optional) Whether to include child terms.
* Default: true
*
* @since 3.1.0
* @access public
* @var array
*/
public $queries = array();
/**
* The relation between the queries. Can be one of 'AND' or 'OR'.
*
* @since 3.1.0
* @access public
* @var string
*/
public $relation;
/**
* Standard response when the query should not return any rows.
*
* @since 3.2.0
* @access private
* @var string
*/
private static $no_results = array( 'join' => '', 'where' => ' AND 0 = 1' );
/**
* Constructor.
*
* Parses a compact tax query and sets defaults.
*
* @since 3.1.0
* @access public
*
* @param array $tax_query A compact tax query:
* array(
* 'relation' => 'OR',
* array(
* 'taxonomy' => 'tax1',
* 'terms' => array( 'term1', 'term2' ),
* 'field' => 'slug',
* ),
* array(
* 'taxonomy' => 'tax2',
* 'terms' => array( 'term-a', 'term-b' ),
* 'field' => 'slug',
* ),
* )
*/
public function __construct( $tax_query ) {
if ( isset( $tax_query['relation'] ) && strtoupper( $tax_query['relation'] ) == 'OR' ) {
$this->relation = 'OR';
} else {
$this->relation = 'AND';
}
$defaults = array(
'taxonomy' => '',
'terms' => array(),
'include_children' => true,
'field' => 'term_id',
'operator' => 'IN',
);
foreach ( $tax_query as $query ) {
if ( ! is_array( $query ) )
continue;
$query = array_merge( $defaults, $query );
$query['terms'] = (array) $query['terms'];
$this->queries[] = $query;
}
}
/**
* Generates SQL clauses to be appended to a main query.
*
* @since 3.1.0
* @access public
*
* @param string $primary_table
* @param string $primary_id_column
* @return array
*/
public function get_sql( $primary_table, $primary_id_column ) {
global $wpdb;
$join = '';
$where = array();
$i = 0;
foreach ( $this->queries as $query ) {
$this->clean_query( $query );
if ( is_wp_error( $query ) ) {
return self::$no_results;
}
extract( $query );
if ( 'IN' == $operator ) {
if ( empty( $terms ) ) {
if ( 'OR' == $this->relation )
continue;
else
return self::$no_results;
}
$terms = implode( ',', $terms );
$alias = $i ? 'tt' . $i : $wpdb->term_relationships;
$join .= " INNER JOIN $wpdb->term_relationships";
$join .= $i ? " AS $alias" : '';
$join .= " ON ($primary_table.$primary_id_column = $alias.object_id)";
$where[] = "$alias.term_taxonomy_id $operator ($terms)";
} elseif ( 'NOT IN' == $operator ) {
if ( empty( $terms ) )
continue;
$terms = implode( ',', $terms );
$where[] = "$primary_table.$primary_id_column NOT IN (
SELECT object_id
FROM $wpdb->term_relationships
WHERE term_taxonomy_id IN ($terms)
)";
} elseif ( 'AND' == $operator ) {
if ( empty( $terms ) )
continue;
$num_terms = count( $terms );
$terms = implode( ',', $terms );
$where[] = "(
SELECT COUNT(1)
FROM $wpdb->term_relationships
WHERE term_taxonomy_id IN ($terms)
AND object_id = $primary_table.$primary_id_column
) = $num_terms";
}
$i++;
}
if ( !empty( $where ) )
$where = ' AND ( ' . implode( " $this->relation ", $where ) . ' )';
else
$where = '';
return compact( 'join', 'where' );
}
/**
* Validates a single query.
*
* @since 3.2.0
* @access private
*
* @param array &$query The single query
*/
private function clean_query( &$query ) {
if ( ! taxonomy_exists( $query['taxonomy'] ) ) {
$query = new WP_Error( 'Invalid taxonomy' );
return;
}
$query['terms'] = array_unique( (array) $query['terms'] );
if ( is_taxonomy_hierarchical( $query['taxonomy'] ) && $query['include_children'] ) {
$this->transform_query( $query, 'term_id' );
if ( is_wp_error( $query ) )
return;
$children = array();
foreach ( $query['terms'] as $term ) {
$children = array_merge( $children, get_term_children( $term, $query['taxonomy'] ) );
$children[] = $term;
}
$query['terms'] = $children;
}
$this->transform_query( $query, 'term_taxonomy_id' );
}
/**
* Transforms a single query, from one field to another.
*
* @since 3.2.0
*
* @param array &$query The single query
* @param string $resulting_field The resulting field
*/
public function transform_query( &$query, $resulting_field ) {
global $wpdb;
if ( empty( $query['terms'] ) )
return;
if ( $query['field'] == $resulting_field )
return;
$resulting_field = esc_sql( $resulting_field );
switch ( $query['field'] ) {
case 'slug':
case 'name':
$terms = "'" . implode( "','", array_map( 'sanitize_title_for_query', $query['terms'] ) ) . "'";
$terms = $wpdb->get_col( "
SELECT $wpdb->term_taxonomy.$resulting_field
FROM $wpdb->term_taxonomy
INNER JOIN $wpdb->terms USING (term_id)
WHERE taxonomy = '{$query['taxonomy']}'
AND $wpdb->terms.{$query['field']} IN ($terms)
" );
break;
case 'term_taxonomy_id':
$terms = implode( ',', array_map( 'intval', $query['terms'] ) );
$terms = $wpdb->get_col( "
SELECT $resulting_field
FROM $wpdb->term_taxonomy
WHERE term_taxonomy_id IN ($terms)
" );
break;
default:
$terms = implode( ',', array_map( 'intval', $query['terms'] ) );
$terms = $wpdb->get_col( "
SELECT $resulting_field
FROM $wpdb->term_taxonomy
WHERE taxonomy = '{$query['taxonomy']}'
AND term_id IN ($terms)
" );
}
if ( 'AND' == $query['operator'] && count( $terms ) < count( $query['terms'] ) ) {
$query = new WP_Error( 'Inexistent terms' );
return;
}
$query['terms'] = $terms;
$query['field'] = $resulting_field;
}
}
/**
* Get all Term data from database by Term ID.
*
* The usage of the get_term function is to apply filters to a term object. It
* is possible to get a term object from the database before applying the
* filters.
*
* $term ID must be part of $taxonomy, to get from the database. Failure, might
* be able to be captured by the hooks. Failure would be the same value as $wpdb
* returns for the get_row method.
*
* There are two hooks, one is specifically for each term, named 'get_term', and
* the second is for the taxonomy name, 'term_$taxonomy'. Both hooks gets the
* term object, and the taxonomy name as parameters. Both hooks are expected to
* return a Term object.
*
* 'get_term' hook - Takes two parameters the term Object and the taxonomy name.
* Must return term object. Used in get_term() as a catch-all filter for every
* $term.
*
* 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy
* name. Must return term object. $taxonomy will be the taxonomy name, so for
* example, if 'category', it would be 'get_category' as the filter name. Useful
* for custom taxonomies or plugging into default taxonomies.
*
* @package WordPress
* @subpackage Taxonomy
* @since 2.3.0
*
* @uses $wpdb
* @uses sanitize_term() Cleanses the term based on $filter context before returning.
* @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
*
* @param int|object $term If integer, will get from database. If object will apply filters and return $term.
* @param string $taxonomy Taxonomy name that $term is part of.
* @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
* @param string $filter Optional, default is raw or no WordPress defined filter will applied.
* @return mixed|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not
* exist then WP_Error will be returned.
*/
function get_term($term, $taxonomy, $output = OBJECT, $filter = 'raw') {
global $wpdb;
$null = null;
if ( empty($term) ) {
$error = new WP_Error('invalid_term', __('Empty Term'));
return $error;
}
if ( ! taxonomy_exists($taxonomy) ) {
$error = new WP_Error('invalid_taxonomy', __('Invalid taxonomy'));
return $error;
}
if ( is_object($term) && empty($term->filter) ) {
wp_cache_add($term->term_id, $term, $taxonomy);
$_term = $term;
} else {
if ( is_object($term) )
$term = $term->term_id;
if ( !$term = (int) $term )
return $null;
if ( ! $_term = wp_cache_get($term, $taxonomy) ) {
$_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE tt.taxonomy = %s AND t.term_id = %d LIMIT 1", $taxonomy, $term) );
if ( ! $_term )
return $null;
wp_cache_add($term, $_term, $taxonomy);
}
}
$_term = apply_filters('get_term', $_term, $taxonomy);
$_term = apply_filters("get_$taxonomy", $_term, $taxonomy);
$_term = sanitize_term($_term, $taxonomy, $filter);
if ( $output == OBJECT ) {
return $_term;
} elseif ( $output == ARRAY_A ) {
$__term = get_object_vars($_term);
return $__term;
} elseif ( $output == ARRAY_N ) {
$__term = array_values(get_object_vars($_term));
return $__term;
} else {
return $_term;
}
}
/**
* Get all Term data from database by Term field and data.
*
* Warning: $value is not escaped for 'name' $field. You must do it yourself, if
* required.
*
* The default $field is 'id', therefore it is possible to also use null for
* field, but not recommended that you do so.
*
* If $value does not exist, the return value will be false. If $taxonomy exists
* and $field and $value combinations exist, the Term will be returned.
*
* @package WordPress
* @subpackage Taxonomy
* @since 2.3.0
*
* @uses $wpdb
* @uses sanitize_term() Cleanses the term based on $filter context before returning.
* @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
*
* @param string $field Either 'slug', 'name', or 'id'
* @param string|int $value Search for this term value
* @param string $taxonomy Taxonomy Name
* @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
* @param string $filter Optional, default is raw or no WordPress defined filter will applied.
* @return mixed Term Row from database. Will return false if $taxonomy does not exist or $term was not found.
*/
function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw') {
global $wpdb;
if ( ! taxonomy_exists($taxonomy) )
return false;
if ( 'slug' == $field ) {
$field = 't.slug';
$value = sanitize_title($value);
if ( empty($value) )
return false;
} else if ( 'name' == $field ) {
// Assume already escaped
$value = stripslashes($value);
$field = 't.name';
} else {
$term = get_term( (int) $value, $taxonomy, $output, $filter);
if ( is_wp_error( $term ) )
$term = false;
return $term;
}
$term = $wpdb->get_row( $wpdb->prepare( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE tt.taxonomy = %s AND $field = %s LIMIT 1", $taxonomy, $value) );
if ( !$term )
return false;
wp_cache_add($term->term_id, $term, $taxonomy);
$term = apply_filters('get_term', $term, $taxonomy);
$term = apply_filters("get_$taxonomy", $term, $taxonomy);
$term = sanitize_term($term, $taxonomy, $filter);
if ( $output == OBJECT ) {
return $term;
} elseif ( $output == ARRAY_A ) {
return get_object_vars($term);
} elseif ( $output == ARRAY_N ) {
return array_values(get_object_vars($term));
} else {
return $term;
}
}
/**
* Merge all term children into a single array of their IDs.
*
* This recursive function will merge all of the children of $term into the same
* array of term IDs. Only useful for taxonomies which are hierarchical.
*
* Will return an empty array if $term does not exist in $taxonomy.
*
* @package WordPress
* @subpackage Taxonomy
* @since 2.3.0
*
* @uses $wpdb
* @uses _get_term_hierarchy()
* @uses get_term_children() Used to get the children of both $taxonomy and the parent $term
*
* @param string $term_id ID of Term to get children
* @param string $taxonomy Taxonomy Name
* @return array|WP_Error List of Term Objects. WP_Error returned if $taxonomy does not exist
*/
function get_term_children( $term_id, $taxonomy ) {