Make WordPress Core

Ticket #8087: get_terms.diff

File get_terms.diff, 7.2 KB (added by filosofo, 16 years ago)
  • wp-includes/taxonomy.php

     
    505505}
    506506
    507507/**
    508  * Retrieve the terms in taxonomy or list of taxonomies.
     508 * Retrieve the terms in a given taxonomy or list of taxonomies.
    509509 *
    510510 * You can fully inject any customizations to the query before it is sent, as
    511511 * well as control the output with a filter.
     
    518518 * The 'list_terms_exclusions' filter passes the compiled exclusions along with
    519519 * the $args.
    520520 *
    521  * The list that $args can contain, which will overwrite the defaults.
     521 * The list of arguments that $args can contain, which will overwrite the defaults:
    522522 *
    523523 * orderby - Default is 'name'. Can be name, count, or nothing (will use
    524524 * term_id).
    525525 *
    526526 * order - Default is ASC. Can use DESC.
    527  * hide_empty - Default is true. Will not return empty $terms.
    528  * fields - Default is all.
    529  * slug - Any terms that has this value. Default is empty string.
    530  * hierarchical - Whether to return hierarchical taxonomy. Default is true.
    531  * name__like - Default is empty string.
    532527 *
    533  * The argument 'pad_counts' will count all of the children along with the
    534  * $terms.
     528 * hide_empty - Default is true. Will not return empty terms, which means
     529 * terms whose count is 0 according to the given taxonomy.
     530 *
     531 * exclude - Default is an empty string.  A comma- or space-delimited string
     532 * of term ids to exclude from the return array.  If 'include' is non-empty,
     533 * 'exclude' is ignored.
    535534 *
    536  * The 'get' argument allows for overwriting 'hide_empty' and 'child_of', which
    537  * can be done by setting the value to 'all', instead of its default empty
    538  * string value.
     535 * include - Default is an empty string.  A comma- or space-delimited string
     536 * of term ids to include in the return array.
     537 *
     538 * number - The maximum number of terms to return.  Default is empty.
     539 *
     540 * offset - The number by which to offset the terms query.
    539541 *
    540  * The 'child_of' argument will be used if you use multiple taxonomy or the
    541  * first $taxonomy isn't hierarchical or 'parent' isn't used. The default is 0,
    542  * which will be translated to a false value. If 'child_of' is set, then
    543  * 'child_of' value will be tested against $taxonomy to see if 'child_of' is
    544  * contained within. Will return an empty array if test fails.
     542 * fields - Default is 'all', which returns an array of term objects.
     543 * If 'fields' is 'ids' or 'names', returns an array of
     544 * integers or strings, respectively.
    545545 *
    546  * If 'parent' is set, then it will be used to test against the first taxonomy.
    547  * Much like 'child_of'. Will return an empty array if the test fails.
     546 * slug - Returns terms whose "slug" matches this value. Default is empty string.
     547 *
     548 * hierarchical - Whether to include terms that have non-empty descendants
     549 * (even if 'hide_empty' is set to true).
     550 *
     551 * search - Returned terms' names will contain the value of 'search',
     552 * case-insensitive.  Default is an empty string.
    548553 *
     554 * name__like - Returned terms' names will begin with the value of 'name__like',
     555 * case-insensitive. Default is empty string.
     556 *
     557 * The argument 'pad_counts', if set to true will include the quantity of a term's
     558 * children in the quantity of each term's "count" object variable.
     559 *
     560 * The 'get' argument, if set to 'all' instead of its default empty string,
     561 * returns terms regardless of ancestry or whether the terms are empty.
     562 *
     563 * The 'child_of' argument, when used, should be set to the integer of a term ID.  Its default
     564 * is 0.  If set to a non-zero value, all returned terms will be descendants
     565 * of that term according to the given taxonomy.  Hence 'child_of' is set to 0
     566 * if more than one taxonomy is passed in $taxonomies, because multiple taxonomies
     567 * make term ancestry ambiguous.
     568 *
     569 * The 'parent' argument, when used, should be set to the integer of a term ID.  Its default is
     570 * the empty string '', which has a different meaning from the integer 0.
     571 * If set to an integer value, all returned terms will have as an immediate
     572 * ancestor the term whose ID is specified by that integer according to the given taxonomy.
     573 * The 'parent' argument is different from 'child_of' in that a term X is considered a 'parent'
     574 * of term Y only if term X is the father of term Y, not its grandfather or great-grandfather, etc.
     575 *
    549576 * @package WordPress
    550577 * @subpackage Taxonomy
    551578 * @since 2.3.0
     
    706733        if ( 'all' == $fields )
    707734                $select_this = 't.*, tt.*';
    708735        else if ( 'ids' == $fields )
    709                 $select_this = 't.term_id';
     736                $select_this = 't.term_id, tt.parent, tt.count';
    710737        else if ( 'names' == $fields )
    711                 $select_this = 't.name';
     738                $select_this = 't.term_id, tt.parent, tt.count, t.name';
    712739
    713740        $query = "SELECT $select_this FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE tt.taxonomy IN ($in_taxonomies) $where ORDER BY $orderby $order $number";
    714741
     
    716743                $terms = $wpdb->get_results($query);
    717744                update_term_cache($terms);
    718745        } else if ( ('ids' == $fields) || ('names' == $fields) ) {
    719                 $terms = $wpdb->get_col($query);
     746                $terms = $wpdb->get_results($query);
    720747        }
    721748
    722749        if ( empty($terms) ) {
     
    726753                return $terms;
    727754        }
    728755
    729         if ( $child_of || $hierarchical ) {
     756        if ( $child_of ) {
    730757                $children = _get_term_hierarchy($taxonomies[0]);
    731758                if ( ! empty($children) )
    732759                        $terms = & _get_term_children($child_of, $terms, $taxonomies[0]);
    733760        }
    734761
    735762        // Update term counts to include children.
    736         if ( $pad_counts )
     763        if ( $pad_counts && 'all' == $fields )
    737764                _pad_term_counts($terms, $taxonomies[0]);
    738765
    739766        // Make sure we show empty categories that have children.
     
    752779                }
    753780        }
    754781        reset ( $terms );
     782       
     783        $_terms = array();
     784        if ( 'ids' == $fields ) {
     785                while ( $term = array_shift($terms) )
     786                        $_terms[] = $term->term_id;
     787                $terms = $_terms;
     788        } elseif ( 'names' == $fields ) {
     789                while ( $term = array_shift($terms) )
     790                        $_terms[] = $term->name;
     791                $terms = $_terms;
     792        }
    755793
    756794        wp_cache_add( $cache_key, $terms, 'terms' );
    757795
     
    18891927
    18901928
    18911929/**
    1892  * Get array of child terms.
     1930 * Get the subset of $terms that are descendants of $term_id.
    18931931 *
    1894  * If $terms is an array of objects, then objects will returned from the
    1895  * function. If $terms is an array of IDs, then an array of ids of children will
    1896  * be returned.
     1932 * If $terms is an array of objects, then _get_term_children returns an array of objects.
     1933 * If $terms is an array of IDs, then _get_term_children returns an array of IDs.
    18971934 *
    18981935 * @package WordPress
    18991936 * @subpackage Taxonomy
    19001937 * @access private
    19011938 * @since 2.3.0
    19021939 *
    1903  * @param int $term_id Look for this Term ID in $terms
    1904  * @param array $terms List of Term IDs
    1905  * @param string $taxonomy Term Context
    1906  * @return array Empty if $terms is empty else returns full list of child terms.
     1940 * @param int $term_id The ancestor term: all returned terms should be descendants of $term_id.
     1941 * @param array $terms The set of terms---either an array of term objects or term IDs---from which those that are descendants of $term_id will be chosen.
     1942 * @param string $taxonomy The taxonomy which determines the hierarchy of the terms.
     1943 * @return array The subset of $terms that are descendants of $term_id.
    19071944 */
    19081945function &_get_term_children($term_id, $terms, $taxonomy) {
    19091946        $empty_array = array();