/** * Parse and sanitize 'orderby' keys passed to the user query. * * @since 4.2.0 * @access protected * * @global wpdb $wpdb WordPress database abstraction object. * * @param string $orderby Alias for the field to order by. * @return string Value to used in the ORDER clause, if `$orderby` is valid. */ protected function parse_orderby($orderby) { global $wpdb; $meta_query_clauses = $this->meta_query->get_clauses(); $_orderby = ''; if (in_array($orderby, array('login', 'nicename', 'email', 'url', 'registered'))) { $_orderby = 'user_' . $orderby; } elseif (in_array($orderby, array('user_login', 'user_nicename', 'user_email', 'user_url', 'user_registered'))) { $_orderby = $orderby; } elseif ('name' == $orderby || 'display_name' == $orderby) { $_orderby = 'display_name'; } elseif ('post_count' == $orderby) { // todo: avoid the JOIN $where = get_posts_by_author_sql('post'); $this->query_from .= " LEFT OUTER JOIN (\n\t\t\t\tSELECT post_author, COUNT(*) as post_count\n\t\t\t\tFROM {$wpdb->posts}\n\t\t\t\t{$where}\n\t\t\t\tGROUP BY post_author\n\t\t\t) p ON ({$wpdb->users}.ID = p.post_author)\n\t\t\t"; $_orderby = 'post_count'; } elseif ('ID' == $orderby || 'id' == $orderby) { $_orderby = 'ID'; } elseif ('meta_value' == $orderby || $this->get('meta_key') == $orderby) { $_orderby = "{$wpdb->usermeta}.meta_value"; } elseif ('meta_value_num' == $orderby) { $_orderby = "{$wpdb->usermeta}.meta_value+0"; } elseif ('include' === $orderby && !empty($this->query_vars['include'])) { $include = wp_parse_id_list($this->query_vars['include']); $include_sql = implode(',', $include); $_orderby = "FIELD( {$wpdb->users}.ID, {$include_sql} )"; } elseif (isset($meta_query_clauses[$orderby])) { $meta_clause = $meta_query_clauses[$orderby]; $_orderby = sprintf("CAST(%s.meta_value AS %s)", esc_sql($meta_clause['alias']), esc_sql($meta_clause['cast'])); } return $_orderby; }
/** * 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. * * The {@see 'get_terms'} filter will be called when the cache has the term and will * pass the found term along with the array of $taxonomies and array of $args. * This filter is also called before the array of terms is passed and will pass * the array of terms, along with the $taxonomies and $args. * * The {@see 'list_terms_exclusions'} filter passes the compiled exclusions along with * the $args. * * The {@see 'get_terms_orderby'} filter passes the `ORDER BY` clause for the query * along with the $args array. * * @since 2.3.0 * @since 4.2.0 Introduced 'name' and 'childless' parameters. * @since 4.4.0 Introduced the ability to pass 'term_id' as an alias of 'id' for the `orderby` parameter. * Introduced the 'meta_query' and 'update_term_meta_cache' parameters. Converted to return * a list of WP_Term objects. * @since 4.5.0 Introduced 'meta_key' and 'meta_value' parameters. Introduced the ability to order results by metadata. * * @global wpdb $wpdb WordPress database abstraction object. * @global array $wp_filter * * @param string|array $taxonomies Taxonomy name or list of Taxonomy names. * @param array|string $args { * Optional. Array or string of arguments to get terms. * * @type string $orderby Field(s) to order terms by. Accepts term fields ('name', 'slug', * 'term_group', 'term_id', 'id', 'description'), 'count' for term * taxonomy count, 'include' to match the 'order' of the $include param, * 'meta_value', 'meta_value_num', the value of `$meta_key`, the array * keys of `$meta_query`, or 'none' to omit the ORDER BY clause. * Defaults to 'name'. * @type string $order Whether to order terms in ascending or descending order. * Accepts 'ASC' (ascending) or 'DESC' (descending). * Default 'ASC'. * @type bool|int $hide_empty Whether to hide terms not assigned to any posts. Accepts * 1|true or 0|false. Default 1|true. * @type array|string $include Array or comma/space-separated string of term ids to include. * Default empty array. * @type array|string $exclude Array or comma/space-separated string of term ids to exclude. * If $include is non-empty, $exclude is ignored. * Default empty array. * @type array|string $exclude_tree Array or comma/space-separated string of term ids to exclude * along with all of their descendant terms. If $include is * non-empty, $exclude_tree is ignored. Default empty array. * @type int|string $number Maximum number of terms to return. Accepts ''|0 (all) or any * positive number. Default ''|0 (all). * @type int $offset The number by which to offset the terms query. Default empty. * @type string $fields Term fields to query for. Accepts 'all' (returns an array of complete * term objects), 'ids' (returns an array of ids), 'id=>parent' (returns * an associative array with ids as keys, parent term IDs as values), * 'names' (returns an array of term names), 'count' (returns the number * of matching terms), 'id=>name' (returns an associative array with ids * as keys, term names as values), or 'id=>slug' (returns an associative * array with ids as keys, term slugs as values). Default 'all'. * @type string|array $name Optional. Name or array of names to return term(s) for. Default empty. * @type string|array $slug Optional. Slug or array of slugs to return term(s) for. Default empty. * @type bool $hierarchical Whether to include terms that have non-empty descendants (even * if $hide_empty is set to true). Default true. * @type string $search Search criteria to match terms. Will be SQL-formatted with * wildcards before and after. Default empty. * @type string $name__like Retrieve terms with criteria by which a term is LIKE $name__like. * Default empty. * @type string $description__like Retrieve terms where the description is LIKE $description__like. * Default empty. * @type bool $pad_counts Whether to pad the quantity of a term's children in the quantity * of each term's "count" object variable. Default false. * @type string $get Whether to return terms regardless of ancestry or whether the terms * are empty. Accepts 'all' or empty (disabled). Default empty. * @type int $child_of Term ID to retrieve child terms of. If multiple taxonomies * are passed, $child_of is ignored. Default 0. * @type int|string $parent Parent term ID to retrieve direct-child terms of. Default empty. * @type bool $childless True to limit results to terms that have no children. This parameter * has no effect on non-hierarchical taxonomies. Default false. * @type string $cache_domain Unique cache key to be produced when this query is stored in an * object cache. Default is 'core'. * @type bool $update_term_meta_cache Whether to prime meta caches for matched terms. Default true. * @type array $meta_query Meta query clauses to limit retrieved terms by. * See `WP_Meta_Query`. Default empty. * @type string $meta_key Limit terms to those matching a specific metadata key. Can be used in * conjunction with `$meta_value`. * @type string $meta_value Limit terms to those matching a specific metadata value. Usually used * in conjunction with `$meta_key`. * } * @return array|int|WP_Error List of WP_Term instances and their children. Will return WP_Error, if any of $taxonomies * do not exist. */ function get_terms($taxonomies, $args = '') { global $wpdb; $empty_array = array(); $single_taxonomy = !is_array($taxonomies) || 1 === count($taxonomies); if (!is_array($taxonomies)) { $taxonomies = array($taxonomies); } foreach ($taxonomies as $taxonomy) { if (!taxonomy_exists($taxonomy)) { return new WP_Error('invalid_taxonomy', __('Invalid taxonomy')); } } $defaults = array('orderby' => 'name', 'order' => 'ASC', 'hide_empty' => true, 'include' => array(), 'exclude' => array(), 'exclude_tree' => array(), 'number' => '', 'offset' => '', 'fields' => 'all', 'name' => '', 'slug' => '', 'hierarchical' => true, 'search' => '', 'name__like' => '', 'description__like' => '', 'pad_counts' => false, 'get' => '', 'child_of' => 0, 'parent' => '', 'childless' => false, 'cache_domain' => 'core', 'update_term_meta_cache' => true, 'meta_query' => ''); /** * Filter the terms query default arguments. * * Use 'get_terms_args' to filter the passed arguments. * * @since 4.4.0 * * @param array $defaults An array of default get_terms() arguments. * @param array $taxonomies An array of taxonomies. */ $args = wp_parse_args($args, apply_filters('get_terms_defaults', $defaults, $taxonomies)); $args['number'] = absint($args['number']); $args['offset'] = absint($args['offset']); // Save queries by not crawling the tree in the case of multiple taxes or a flat tax. $has_hierarchical_tax = false; foreach ($taxonomies as $_tax) { if (is_taxonomy_hierarchical($_tax)) { $has_hierarchical_tax = true; } } if (!$has_hierarchical_tax) { $args['hierarchical'] = false; $args['pad_counts'] = false; } // 'parent' overrides 'child_of'. if (0 < intval($args['parent'])) { $args['child_of'] = false; } if ('all' == $args['get']) { $args['childless'] = false; $args['child_of'] = 0; $args['hide_empty'] = 0; $args['hierarchical'] = false; $args['pad_counts'] = false; } /** * Filter the terms query arguments. * * @since 3.1.0 * * @param array $args An array of get_terms() arguments. * @param array $taxonomies An array of taxonomies. */ $args = apply_filters('get_terms_args', $args, $taxonomies); // Avoid the query if the queried parent/child_of term has no descendants. $child_of = $args['child_of']; $parent = $args['parent']; if ($child_of) { $_parent = $child_of; } elseif ($parent) { $_parent = $parent; } else { $_parent = false; } if ($_parent) { $in_hierarchy = false; foreach ($taxonomies as $_tax) { $hierarchy = _get_term_hierarchy($_tax); if (isset($hierarchy[$_parent])) { $in_hierarchy = true; } } if (!$in_hierarchy) { return $empty_array; } } $_orderby = strtolower($args['orderby']); if ('count' == $_orderby) { $orderby = 'tt.count'; } elseif ('name' == $_orderby) { $orderby = 't.name'; } elseif ('slug' == $_orderby) { $orderby = 't.slug'; } elseif ('include' == $_orderby && !empty($args['include'])) { $include = implode(',', array_map('absint', $args['include'])); $orderby = "FIELD( t.term_id, {$include} )"; } elseif ('term_group' == $_orderby) { $orderby = 't.term_group'; } elseif ('description' == $_orderby) { $orderby = 'tt.description'; } elseif ('none' == $_orderby) { $orderby = ''; } elseif (empty($_orderby) || 'id' == $_orderby || 'term_id' === $_orderby) { $orderby = 't.term_id'; } else { $orderby = 't.name'; } /** * Filter the ORDERBY clause of the terms query. * * @since 2.8.0 * * @param string $orderby `ORDERBY` clause of the terms query. * @param array $args An array of terms query arguments. * @param array $taxonomies An array of taxonomies. */ $orderby = apply_filters('get_terms_orderby', $orderby, $args, $taxonomies); $order = strtoupper($args['order']); if (!empty($orderby)) { $orderby = "ORDER BY {$orderby}"; } else { $order = ''; } if ('' !== $order && !in_array($order, array('ASC', 'DESC'))) { $order = 'ASC'; } $where = "tt.taxonomy IN ('" . implode("', '", $taxonomies) . "')"; $exclude = $args['exclude']; $exclude_tree = $args['exclude_tree']; $include = $args['include']; $inclusions = ''; if (!empty($include)) { $exclude = ''; $exclude_tree = ''; $inclusions = implode(',', wp_parse_id_list($include)); } if (!empty($inclusions)) { $inclusions = ' AND t.term_id IN ( ' . $inclusions . ' )'; $where .= $inclusions; } $exclusions = array(); if (!empty($exclude_tree)) { $exclude_tree = wp_parse_id_list($exclude_tree); $excluded_children = $exclude_tree; foreach ($exclude_tree as $extrunk) { $excluded_children = array_merge($excluded_children, (array) get_terms($taxonomies[0], array('child_of' => intval($extrunk), 'fields' => 'ids', 'hide_empty' => 0))); } $exclusions = array_merge($excluded_children, $exclusions); } if (!empty($exclude)) { $exclusions = array_merge(wp_parse_id_list($exclude), $exclusions); } // 'childless' terms are those without an entry in the flattened term hierarchy. $childless = (bool) $args['childless']; if ($childless) { foreach ($taxonomies as $_tax) { $term_hierarchy = _get_term_hierarchy($_tax); $exclusions = array_merge(array_keys($term_hierarchy), $exclusions); } } if (!empty($exclusions)) { $exclusions = ' AND t.term_id NOT IN (' . implode(',', array_map('intval', $exclusions)) . ')'; } else { $exclusions = ''; } /** * Filter the terms to exclude from the terms query. * * @since 2.3.0 * * @param string $exclusions `NOT IN` clause of the terms query. * @param array $args An array of terms query arguments. * @param array $taxonomies An array of taxonomies. */ $exclusions = apply_filters('list_terms_exclusions', $exclusions, $args, $taxonomies); if (!empty($exclusions)) { $where .= $exclusions; } if (!empty($args['name'])) { $names = (array) $args['name']; foreach ($names as &$_name) { // `sanitize_term_field()` returns slashed data. $_name = stripslashes(sanitize_term_field('name', $_name, 0, reset($taxonomies), 'db')); } $where .= " AND t.name IN ('" . implode("', '", array_map('esc_sql', $names)) . "')"; } if (!empty($args['slug'])) { if (is_array($args['slug'])) { $slug = array_map('sanitize_title', $args['slug']); $where .= " AND t.slug IN ('" . implode("', '", $slug) . "')"; } else { $slug = sanitize_title($args['slug']); $where .= " AND t.slug = '{$slug}'"; } } if (!empty($args['name__like'])) { $where .= $wpdb->prepare(" AND t.name LIKE %s", '%' . $wpdb->esc_like($args['name__like']) . '%'); } if (!empty($args['description__like'])) { $where .= $wpdb->prepare(" AND tt.description LIKE %s", '%' . $wpdb->esc_like($args['description__like']) . '%'); } if ('' !== $parent) { $parent = (int) $parent; $where .= " AND tt.parent = '{$parent}'"; } $hierarchical = $args['hierarchical']; if ('count' == $args['fields']) { $hierarchical = false; } if ($args['hide_empty'] && !$hierarchical) { $where .= ' AND tt.count > 0'; } $number = $args['number']; $offset = $args['offset']; // Don't limit the query results when we have to descend the family tree. if ($number && !$hierarchical && !$child_of && '' === $parent) { if ($offset) { $limits = 'LIMIT ' . $offset . ',' . $number; } else { $limits = 'LIMIT ' . $number; } } else { $limits = ''; } if (!empty($args['search'])) { $like = '%' . $wpdb->esc_like($args['search']) . '%'; $where .= $wpdb->prepare(' AND ((t.name LIKE %s) OR (t.slug LIKE %s))', $like, $like); } // Meta query support. $join = ''; $distinct = ''; $mquery = new WP_Meta_Query(); $mquery->parse_query_vars($args); $mq_sql = $mquery->get_sql('term', 't', 'term_id'); $meta_clauses = $mquery->get_clauses(); if (!empty($meta_clauses)) { $join .= $mq_sql['join']; $where .= $mq_sql['where']; $distinct .= "DISTINCT"; // 'orderby' support. $allowed_keys = array(); $primary_meta_key = null; $primary_meta_query = reset($meta_clauses); if (!empty($primary_meta_query['key'])) { $primary_meta_key = $primary_meta_query['key']; $allowed_keys[] = $primary_meta_key; } $allowed_keys[] = 'meta_value'; $allowed_keys[] = 'meta_value_num'; $allowed_keys = array_merge($allowed_keys, array_keys($meta_clauses)); if (!empty($args['orderby']) && in_array($args['orderby'], $allowed_keys)) { switch ($args['orderby']) { case $primary_meta_key: case 'meta_value': if (!empty($primary_meta_query['type'])) { $orderby = "ORDER BY CAST({$primary_meta_query['alias']}.meta_value AS {$primary_meta_query['cast']})"; } else { $orderby = "ORDER BY {$primary_meta_query['alias']}.meta_value"; } break; case 'meta_value_num': $orderby = "ORDER BY {$primary_meta_query['alias']}.meta_value+0"; break; default: if (array_key_exists($args['orderby'], $meta_clauses)) { // $orderby corresponds to a meta_query clause. $meta_clause = $meta_clauses[$args['orderby']]; $orderby = "ORDER BY CAST({$meta_clause['alias']}.meta_value AS {$meta_clause['cast']})"; } break; } } } $selects = array(); switch ($args['fields']) { case 'all': $selects = array('t.*', 'tt.*'); break; case 'ids': case 'id=>parent': $selects = array('t.term_id', 'tt.parent', 'tt.count', 'tt.taxonomy'); break; case 'names': $selects = array('t.term_id', 'tt.parent', 'tt.count', 't.name', 'tt.taxonomy'); break; case 'count': $orderby = ''; $order = ''; $selects = array('COUNT(*)'); break; case 'id=>name': $selects = array('t.term_id', 't.name', 'tt.count', 'tt.taxonomy'); break; case 'id=>slug': $selects = array('t.term_id', 't.slug', 'tt.count', 'tt.taxonomy'); break; } $_fields = $args['fields']; /** * Filter the fields to select in the terms query. * * Field lists modified using this filter will only modify the term fields returned * by the function when the `$fields` parameter set to 'count' or 'all'. In all other * cases, the term fields in the results array will be determined by the `$fields` * parameter alone. * * Use of this filter can result in unpredictable behavior, and is not recommended. * * @since 2.8.0 * * @param array $selects An array of fields to select for the terms query. * @param array $args An array of term query arguments. * @param array $taxonomies An array of taxonomies. */ $fields = implode(', ', apply_filters('get_terms_fields', $selects, $args, $taxonomies)); $join .= " INNER JOIN {$wpdb->term_taxonomy} AS tt ON t.term_id = tt.term_id"; $pieces = array('fields', 'join', 'where', 'distinct', 'orderby', 'order', 'limits'); /** * Filter the terms query SQL clauses. * * @since 3.1.0 * * @param array $pieces Terms query SQL clauses. * @param array $taxonomies An array of taxonomies. * @param array $args An array of terms query arguments. */ $clauses = apply_filters('terms_clauses', compact($pieces), $taxonomies, $args); $fields = isset($clauses['fields']) ? $clauses['fields'] : ''; $join = isset($clauses['join']) ? $clauses['join'] : ''; $where = isset($clauses['where']) ? $clauses['where'] : ''; $distinct = isset($clauses['distinct']) ? $clauses['distinct'] : ''; $orderby = isset($clauses['orderby']) ? $clauses['orderby'] : ''; $order = isset($clauses['order']) ? $clauses['order'] : ''; $limits = isset($clauses['limits']) ? $clauses['limits'] : ''; $query = "SELECT {$distinct} {$fields} FROM {$wpdb->terms} AS t {$join} WHERE {$where} {$orderby} {$order} {$limits}"; // $args can be anything. Only use the args defined in defaults to compute the key. $key = md5(serialize(wp_array_slice_assoc($args, array_keys($defaults))) . serialize($taxonomies) . $query); $last_changed = wp_cache_get('last_changed', 'terms'); if (!$last_changed) { $last_changed = microtime(); wp_cache_set('last_changed', $last_changed, 'terms'); } $cache_key = "get_terms:{$key}:{$last_changed}"; $cache = wp_cache_get($cache_key, 'terms'); if (false !== $cache) { if ('all' === $_fields) { $cache = array_map('get_term', $cache); } /** * Filter the given taxonomy's terms cache. * * @since 2.3.0 * * @param array $cache Cached array of terms for the given taxonomy. * @param array $taxonomies An array of taxonomies. * @param array $args An array of get_terms() arguments. */ return apply_filters('get_terms', $cache, $taxonomies, $args); } if ('count' == $_fields) { return $wpdb->get_var($query); } $terms = $wpdb->get_results($query); if ('all' == $_fields) { update_term_cache($terms); } // Prime termmeta cache. if ($args['update_term_meta_cache']) { $term_ids = wp_list_pluck($terms, 'term_id'); update_termmeta_cache($term_ids); } if (empty($terms)) { wp_cache_add($cache_key, array(), 'terms', DAY_IN_SECONDS); /** This filter is documented in wp-includes/taxonomy.php */ return apply_filters('get_terms', array(), $taxonomies, $args); } if ($child_of) { foreach ($taxonomies as $_tax) { $children = _get_term_hierarchy($_tax); if (!empty($children)) { $terms = _get_term_children($child_of, $terms, $_tax); } } } // Update term counts to include children. if ($args['pad_counts'] && 'all' == $_fields) { foreach ($taxonomies as $_tax) { _pad_term_counts($terms, $_tax); } } // Make sure we show empty categories that have children. if ($hierarchical && $args['hide_empty'] && is_array($terms)) { foreach ($terms as $k => $term) { if (!$term->count) { $children = get_term_children($term->term_id, $term->taxonomy); if (is_array($children)) { foreach ($children as $child_id) { $child = get_term($child_id, $term->taxonomy); if ($child->count) { continue 2; } } } // It really is empty. unset($terms[$k]); } } } $_terms = array(); if ('id=>parent' == $_fields) { foreach ($terms as $term) { $_terms[$term->term_id] = $term->parent; } } elseif ('ids' == $_fields) { foreach ($terms as $term) { $_terms[] = $term->term_id; } } elseif ('names' == $_fields) { foreach ($terms as $term) { $_terms[] = $term->name; } } elseif ('id=>name' == $_fields) { foreach ($terms as $term) { $_terms[$term->term_id] = $term->name; } } elseif ('id=>slug' == $_fields) { foreach ($terms as $term) { $_terms[$term->term_id] = $term->slug; } } if (!empty($_terms)) { $terms = $_terms; } if ($number && is_array($terms) && count($terms) > $number) { $terms = array_slice($terms, $offset, $number, true); } wp_cache_add($cache_key, $terms, 'terms', DAY_IN_SECONDS); if ('all' === $_fields) { $terms = array_map('get_term', $terms); } /** This filter is documented in wp-includes/taxonomy.php */ return apply_filters('get_terms', $terms, $taxonomies, $args); }