get_terms() improvements from filosofo. fixes #8087

git-svn-id: http://svn.automattic.com/wordpress/trunk@9652 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/taxonomy.php

@@ -505,7 +505,7 @@ function get_term_to_edit( $id, $taxonomy ) {
 }
 
 /**
- * Retrieve the terms in taxonomy or list of taxonomies.
+ * Retrieve the terms in a given taxonomy or list of taxonomies.
  *
  * You can fully inject any customizations to the query before it is sent, as
  * well as control the output with a filter.
@@ -518,33 +518,60 @@ function get_term_to_edit( $id, $taxonomy ) {
  * The 'list_terms_exclusions' filter passes the compiled exclusions along with
  * the $args.
  *
- * The list that $args can contain, which will overwrite the defaults.
+ * The list of arguments that $args can contain, which will overwrite the defaults:
  *
  * orderby - Default is 'name'. Can be name, count, or nothing (will use
  * term_id).
  *
  * order - Default is ASC. Can use DESC.
- * hide_empty - Default is true. Will not return empty $terms.
- * fields - Default is all.
- * slug - Any terms that has this value. Default is empty string.
- * hierarchical - Whether to return hierarchical taxonomy. Default is true.
- * name__like - Default is empty string.
  *
- * The argument 'pad_counts' will count all of the children along with the
+ * hide_empty - Default is true. Will not return empty terms, which means
- * $terms.
+ * terms whose count is 0 according to the given taxonomy.
+ * 
+ * exclude - Default is an empty string.  A comma- or space-delimited string
+ * of term ids to exclude from the return array.  If 'include' is non-empty, 
+ * 'exclude' is ignored.
  *
- * The 'get' argument allows for overwriting 'hide_empty' and 'child_of', which
+ * include - Default is an empty string.  A comma- or space-delimited string
- * can be done by setting the value to 'all', instead of its default empty
+ * of term ids to include in the return array.
- * string value.
+ * 
+ * number - The maximum number of terms to return.  Default is empty.
+ * 
+ * offset - The number by which to offset the terms query.
  *
- * The 'child_of' argument will be used if you use multiple taxonomy or the
+ * fields - Default is 'all', which returns an array of term objects. 
- * first $taxonomy isn't hierarchical or 'parent' isn't used. The default is 0,
+ * If 'fields' is 'ids' or 'names', returns an array of
- * which will be translated to a false value. If 'child_of' is set, then
+ * integers or strings, respectively.
- * 'child_of' value will be tested against $taxonomy to see if 'child_of' is
- * contained within. Will return an empty array if test fails.
  *
- * If 'parent' is set, then it will be used to test against the first taxonomy.
+ * slug - Returns terms whose "slug" matches this value. Default is empty string.
- * Much like 'child_of'. Will return an empty array if the test fails.
+ * 
+ * hierarchical - Whether to include terms that have non-empty descendants
+ * (even if 'hide_empty' is set to true).
+ * 
+ * search - Returned terms' names will contain the value of 'search',
+ * case-insensitive.  Default is an empty string.
+ *
+ * name__like - Returned terms' names will begin with the value of 'name__like',
+ * case-insensitive. Default is empty string.
+ *
+ * The argument 'pad_counts', if set to true will include the quantity of a term's
+ * children in the quantity of each term's "count" object variable.
+ *
+ * The 'get' argument, if set to 'all' instead of its default empty string,
+ * returns terms regardless of ancestry or whether the terms are empty.
+ *
+ * The 'child_of' argument, when used, should be set to the integer of a term ID.  Its default
+ * is 0.  If set to a non-zero value, all returned terms will be descendants 
+ * of that term according to the given taxonomy.  Hence 'child_of' is set to 0 
+ * if more than one taxonomy is passed in $taxonomies, because multiple taxonomies 
+ * make term ancestry ambiguous.
+ *
+ * The 'parent' argument, when used, should be set to the integer of a term ID.  Its default is
+ * the empty string '', which has a different meaning from the integer 0.
+ * If set to an integer value, all returned terms will have as an immediate 
+ * ancestor the term whose ID is specified by that integer according to the given taxonomy.
+ * The 'parent' argument is different from 'child_of' in that a term X is considered a 'parent'
+ * of term Y only if term X is the father of term Y, not its grandfather or great-grandfather, etc.
  *
  * @package WordPress
  * @subpackage Taxonomy
@@ -706,9 +733,9 @@ function &get_terms($taxonomies, $args = '') {
 	if ( 'all' == $fields )
 		$select_this = 't.*, tt.*';
 	else if ( 'ids' == $fields )
-		$select_this = 't.term_id';
+		$select_this = 't.term_id, tt.parent, tt.count';
 	else if ( 'names' == $fields )
-		$select_this = 't.name';
+		$select_this = 't.term_id, tt.parent, tt.count, t.name';
 
 	$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";
 
@@ -716,7 +743,7 @@ function &get_terms($taxonomies, $args = '') {
 		$terms = $wpdb->get_results($query);
 		update_term_cache($terms);
 	} else if ( ('ids' == $fields) || ('names' == $fields) ) {
-		$terms = $wpdb->get_col($query);
+		$terms = $wpdb->get_results($query);
 	}
 
 	if ( empty($terms) ) {
@@ -726,14 +753,14 @@ function &get_terms($taxonomies, $args = '') {
 		return $terms;
 	}
 
-	if ( $child_of || $hierarchical ) {
+	if ( $child_of ) {
 		$children = _get_term_hierarchy($taxonomies[0]);
 		if ( ! empty($children) )
 			$terms = & _get_term_children($child_of, $terms, $taxonomies[0]);
 	}
 
 	// Update term counts to include children.
-	if ( $pad_counts )
+	if ( $pad_counts && 'all' == $fields )
 		_pad_term_counts($terms, $taxonomies[0]);
 
 	// Make sure we show empty categories that have children.
@@ -752,6 +779,17 @@ function &get_terms($taxonomies, $args = '') {
 		}
 	}
 	reset ( $terms );
+	
+	$_terms = array();
+	if ( 'ids' == $fields ) {
+		while ( $term = array_shift($terms) )
+			$_terms[] = $term->term_id;
+		$terms = $_terms;
+	} elseif ( 'names' == $fields ) {
+		while ( $term = array_shift($terms) )
+			$_terms[] = $term->name;
+		$terms = $_terms;
+	}
 
 	wp_cache_add( $cache_key, $terms, 'terms' );
 
@@ -1894,21 +1932,20 @@ function _get_term_hierarchy($taxonomy) {
 
 
 /**
- * Get array of child terms.
+ * Get the subset of $terms that are descendants of $term_id.
  *
- * If $terms is an array of objects, then objects will returned from the
+ * If $terms is an array of objects, then _get_term_children returns an array of objects.
- * function. If $terms is an array of IDs, then an array of ids of children will
+ * If $terms is an array of IDs, then _get_term_children returns an array of IDs.
- * be returned.
  *
  * @package WordPress
  * @subpackage Taxonomy
  * @access private
  * @since 2.3.0
  *
- * @param int $term_id Look for this Term ID in $terms
+ * @param int $term_id The ancestor term: all returned terms should be descendants of $term_id.
- * @param array $terms List of Term IDs
+ * @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.
- * @param string $taxonomy Term Context
+ * @param string $taxonomy The taxonomy which determines the hierarchy of the terms.
- * @return array Empty if $terms is empty else returns full list of child terms.
+ * @return array The subset of $terms that are descendants of $term_id. 
  */
 function &_get_term_children($term_id, $terms, $taxonomy) {
 	$empty_array = array();