WordPress.org

Make WordPress Core

Changeset 36614


Ignore:
Timestamp:
02/22/2016 10:16:37 PM (2 years 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.