WordPress.org

Make WordPress Core

Changeset 36614


Ignore:
Timestamp:
02/22/16 22:16:37 (19 months ago)
Author:
boonebgorges
Message:

Allow get_terms() to fetch terms regardless of taxonomy.

get_terms() has historically required that a taxonomy be specified when
querying terms. This requirement is related to the fact that terms could
formerly be shared between taxonomies, making $taxonomies critical for
disambiguation. Since terms can no longer be shared as of 4.4, it'
s desirable to be able to query for terms regardless of what taxonomy they're in.

Because it's now optional to pass taxonomies, it's no longer necessary to have
$taxonomies as the first (and required) parameter for get_terms(). The new
function signature is get_terms( $args ), where 'taxonomy' can (optionally) be
passed as part of the $args array. This syntax is more consistent with
functions like get_users() and get_posts().

We've maintained backward compatibility by always giving precedence to the old
argument format. If a second parameter is detected, or if it's detected that
the first parameter is a list of taxonomy names rather than an $args array,
get_terms() will parse the function arguments in the legacy fashion.

Props flixos90, swissspidy, DrewAPicture, boonebgorges.
Fixes #35495.

Location:
trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/taxonomy.php

    r36598 r36614  
    10731073 * along with the $args array. 
    10741074 * 
     1075 * Prior to 4.5.0, the first parameter of `get_terms()` was a taxonomy or list of taxonomies: 
     1076 * 
     1077 *     $terms = get_terms( 'post_tag', array( 
     1078 *         'hide_empty' => false, 
     1079 *     ) ); 
     1080 * 
     1081 * Since 4.5.0, taxonomies should be passed via the 'taxonomy' argument in the `$args` array: 
     1082 * 
     1083 *     $terms = get_terms( array( 
     1084 *         'taxonomy' => 'post_tag', 
     1085 *         'hide_empty' => false, 
     1086 *     ) ); 
     1087 * 
    10751088 * @since 2.3.0 
    10761089 * @since 4.2.0 Introduced 'name' and 'childless' parameters. 
     
    10781091 *              Introduced the 'meta_query' and 'update_term_meta_cache' parameters. Converted to return 
    10791092 *              a list of WP_Term objects. 
    1080  * @since 4.5.0 Introduced 'meta_key' and 'meta_value' parameters. Introduced the ability to order results by metadata. 
     1093 * @since 4.5.0 Changed the function signature so that the `$args` array can be provided as the first parameter. 
     1094 *              Introduced 'meta_key' and 'meta_value' parameters. Introduced the ability to order results by metadata. 
     1095 * 
     1096 * @internal The `$deprecated` parameter is parsed for backward compatibility only. 
    10811097 * 
    10821098 * @global wpdb  $wpdb WordPress database abstraction object. 
    10831099 * @global array $wp_filter 
    10841100 * 
    1085  * @param string|array $taxonomies Taxonomy name or list of Taxonomy names. 
    10861101 * @param array|string $args { 
    10871102 *     Optional. Array or string of arguments to get terms. 
    10881103 * 
     1104 *     @type string|array $taxonomy               Taxonomy name, or array of taxonomies, to which results should 
     1105 *                                                be limited. 
    10891106 *     @type string       $orderby                Field(s) to order terms by. Accepts term fields ('name', 'slug', 
    10901107 *                                                'term_group', 'term_id', 'id', 'description'), 'count' for term 
     
    11451162 *                                                in conjunction with `$meta_key`. 
    11461163 * } 
     1164 * @param array $deprecated Argument array, when using the legacy function parameter format. If present, this 
     1165 *                          parameter will be interpreted as `$args`, and the first function parameter will 
     1166 *                          be parsed as a taxonomy or array of taxonomies. 
    11471167 * @return array|int|WP_Error List of WP_Term instances and their children. Will return WP_Error, if any of $taxonomies 
    11481168 *                            do not exist. 
    11491169 */ 
    1150 function get_terms( $taxonomies, $args = '' ) { 
     1170function get_terms( $args = array(), $deprecated = '' ) { 
    11511171    global $wpdb; 
    1152     $empty_array = array(); 
    1153  
    1154     if ( ! is_array( $taxonomies ) ) { 
    1155         $taxonomies = array( $taxonomies ); 
    1156     } 
    1157  
    1158     foreach ( $taxonomies as $taxonomy ) { 
    1159         if ( ! taxonomy_exists($taxonomy) ) { 
    1160             return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) ); 
    1161         } 
    1162     } 
    11631172 
    11641173    $defaults = array( 
     1174        'taxonomy'               => null, 
    11651175        'orderby'                => 'name', 
    11661176        'order'                  => 'ASC', 
     
    11881198    ); 
    11891199 
     1200    /* 
     1201     * Legacy argument format ($taxonomy, $args) takes precedence. 
     1202     * 
     1203     * We detect legacy argument format by checking if 
     1204     * (a) a second non-empty parameter is passed, or 
     1205     * (b) the first parameter shares no keys with the default array (ie, it's a list of taxonomies) 
     1206     */ 
     1207    $key_intersect  = array_intersect_key( $defaults, (array) $args ); 
     1208    $do_legacy_args = $deprecated || empty( $key_intersect ); 
     1209 
     1210    $taxonomies = null; 
     1211    if ( $do_legacy_args ) { 
     1212        $taxonomies = (array) $args; 
     1213        $args = $deprecated; 
     1214    } elseif ( isset( $args['taxonomy'] ) && null !== $args['taxonomy'] ) { 
     1215        $taxonomies = (array) $args['taxonomy']; 
     1216        unset( $args['taxonomy'] ); 
     1217    } 
     1218 
     1219    $empty_array = array(); 
     1220 
     1221    if ( $taxonomies ) { 
     1222        foreach ( $taxonomies as $taxonomy ) { 
     1223            if ( ! taxonomy_exists($taxonomy) ) { 
     1224                return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) ); 
     1225            } 
     1226        } 
     1227    } 
     1228 
    11901229    /** 
    11911230     * Filter the terms query default arguments. 
     
    12051244    // Save queries by not crawling the tree in the case of multiple taxes or a flat tax. 
    12061245    $has_hierarchical_tax = false; 
    1207     foreach ( $taxonomies as $_tax ) { 
    1208         if ( is_taxonomy_hierarchical( $_tax ) ) { 
    1209             $has_hierarchical_tax = true; 
     1246    if ( $taxonomies ) { 
     1247        foreach ( $taxonomies as $_tax ) { 
     1248            if ( is_taxonomy_hierarchical( $_tax ) ) { 
     1249                $has_hierarchical_tax = true; 
     1250            } 
    12101251        } 
    12111252    } 
     
    13121353    $where_conditions = array(); 
    13131354 
    1314     $where_conditions[] = "tt.taxonomy IN ('" . implode("', '", $taxonomies) . "')"; 
     1355    if ( $taxonomies ) { 
     1356        $where_conditions[] = "tt.taxonomy IN ('" . implode("', '", $taxonomies) . "')"; 
     1357    } 
    13151358 
    13161359    $exclude = $args['exclude']; 
  • trunk/tests/phpunit/tests/term/getTerms.php

    r36485 r36614  
    1010        _clean_term_filters(); 
    1111        wp_cache_delete( 'last_changed', 'terms' ); 
     12    } 
     13 
     14    /** 
     15     * @ticket 35495 
     16     */ 
     17    public function test_should_accept_an_args_array_containing_taxonomy_for_first_parameter() { 
     18        register_taxonomy( 'wptests_tax', 'post' ); 
     19        $term = self::factory()->term->create( array( 'taxonomy' => 'wptests_tax' ) ); 
     20 
     21        $found = get_terms( array( 
     22            'taxonomy' => 'wptests_tax', 
     23            'hide_empty' => false, 
     24            'fields' => 'ids', 
     25            'update_term_meta_cache' => false, 
     26        ) ); 
     27 
     28        $this->assertEqualSets( array( $term ), $found ); 
     29    } 
     30 
     31    /** 
     32     * @ticket 35495 
     33     */ 
     34    public function test_excluding_taxonomy_arg_should_return_terms_from_all_taxonomies() { 
     35        register_taxonomy( 'wptests_tax1', 'post' ); 
     36        register_taxonomy( 'wptests_tax2', 'post' ); 
     37        $t1 = self::factory()->term->create( array( 'taxonomy' => 'wptests_tax1' ) ); 
     38        $t2 = self::factory()->term->create( array( 'taxonomy' => 'wptests_tax2' ) ); 
     39 
     40        $found = get_terms( array( 
     41            'hide_empty' => false, 
     42            'fields' => 'ids', 
     43            'update_term_meta_cache' => false, 
     44        ) ); 
     45 
     46        // There may be other terms lying around, so don't do an exact match. 
     47        $this->assertContains( $t1, $found ); 
     48        $this->assertContains( $t2, $found ); 
    1249    } 
    1350 
Note: See TracChangeset for help on using the changeset viewer.