/**
* Taxonomy API
*
+ * @since 2.3.0
+ *
* @package WordPress
* @subpackage Taxonomy
- * @since 2.3.0
*/
//
* Creates the initial taxonomies.
*
* This function fires twice: in wp-settings.php before plugins are loaded (for
- * backwards compatibility reasons), and again on the 'init' action. We must avoid
- * registering rewrite rules before the 'init' action.
+ * backwards compatibility reasons), and again on the {@see 'init'} action. We must
+ * avoid registering rewrite rules before the {@see 'init'} action.
+ *
+ * @since 2.8.0
+ *
+ * @global WP_Rewrite $wp_rewrite The WordPress rewrite class.
*/
function create_initial_taxonomies() {
global $wp_rewrite;
}
/**
- * Get a list of registered taxonomy objects.
+ * Retrieves a list of registered taxonomy names or objects.
*
* @since 3.0.0
- * @uses $wp_taxonomies
*
- * @param array $args An array of key => value arguments to match against the taxonomy objects.
- * @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
- * @param string $operator The logical operation to perform. 'or' means only one element
- * from the array needs to match; 'and' means all elements must match. The default is 'and'.
- * @return array A list of taxonomy names or objects
+ * @global array $wp_taxonomies The registered taxonomies.
+ *
+ * @param array $args Optional. An array of `key => value` arguments to match against the taxonomy objects.
+ * Default empty array.
+ * @param string $output Optional. The type of output to return in the array. Accepts either taxonomy 'names'
+ * or 'objects'. Default 'names'.
+ * @param string $operator Optional. The logical operation to perform. Accepts 'and' or 'or'. 'or' means only
+ * one element from the array needs to match; 'and' means all elements must match.
+ * Default 'and'.
+ * @return array A list of taxonomy names or objects.
*/
function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' ) {
global $wp_taxonomies;
*
* @since 2.3.0
*
- * @uses $wp_taxonomies
+ * @global array $wp_taxonomies The registered taxonomies.
*
- * @param array|string|object $object Name of the type of taxonomy object, or an object (row from posts)
- * @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
+ * @param array|string|WP_Post $object Name of the type of taxonomy object, or an object (row from posts)
+ * @param string $output Optional. The type of output to return in the array. Accepts either
+ * taxonomy 'names' or 'objects'. Default 'names'.
* @return array The names of all taxonomy of $object_type.
*/
-function get_object_taxonomies($object, $output = 'names') {
+function get_object_taxonomies( $object, $output = 'names' ) {
global $wp_taxonomies;
if ( is_object($object) ) {
*
* @since 2.3.0
*
- * @uses $wp_taxonomies
+ * @global array $wp_taxonomies The registered taxonomies.
*
- * @param string $taxonomy Name of taxonomy object to return
- * @return object|bool The Taxonomy Object or false if $taxonomy doesn't exist
+ * @param string $taxonomy Name of taxonomy object to return.
+ * @return object|false The Taxonomy Object or false if $taxonomy doesn't exist.
*/
function get_taxonomy( $taxonomy ) {
global $wp_taxonomies;
*
* @since 3.0.0
*
- * @uses $wp_taxonomies
+ * @global array $wp_taxonomies The registered taxonomies.
*
- * @param string $taxonomy Name of taxonomy object
+ * @param string $taxonomy Name of taxonomy object.
* @return bool Whether the taxonomy exists.
*/
function taxonomy_exists( $taxonomy ) {
*
* @since 2.3.0
*
- * @param string $taxonomy Name of taxonomy object
- * @return bool Whether the taxonomy is hierarchical
+ * @param string $taxonomy Name of taxonomy object.
+ * @return bool Whether the taxonomy is hierarchical.
*/
function is_taxonomy_hierarchical($taxonomy) {
if ( ! taxonomy_exists($taxonomy) )
* * Defaults to _update_generic_term_count() for taxonomies attached to other object types, such as links.
* - _builtin - true if this taxonomy is a native or "built-in" taxonomy. THIS IS FOR INTERNAL USE ONLY!
*
+ * @todo Document $args as a hash notation.
+ *
* @since 2.3.0
* @since 4.2.0 Introduced `show_in_quick_edit` argument.
*
* @global array $wp_taxonomies Registered taxonomies.
* @global WP $wp WP instance.
*
- * @param string $taxonomy Taxonomy key, must not exceed 32 characters.
+ * @param string $taxonomy Taxonomy key, must not exceed 32 characters.
* @param array|string $object_type Name of the object type for the taxonomy object.
- * @param array|string $args See optional args description above.
- * @return null|WP_Error WP_Error if errors, otherwise null.
+ * @param array|string $args See optional args description above.
+ * @return WP_Error|void WP_Error, if errors.
*/
function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
global $wp_taxonomies, $wp;
* - add_or_remove_items - This string isn't used on hierarchical taxonomies. Default is "Add or remove tags", used in the meta box when JavaScript is disabled.
* - choose_from_most_used - This string isn't used on hierarchical taxonomies. Default is "Choose from the most used tags", used in the meta box.
* - not_found - Default is "No tags found"/"No categories found", used in the meta box and taxonomy list table.
+ * - no_terms - Default is "No tags"/"No categories", used in the posts and media list tables.
*
* Above, the first default value is for non-hierarchical taxonomies (like tags) and the second one is for hierarchical taxonomies (like categories).
*
+ * @todo Better documentation for the labels array.
+ *
* @since 3.0.0
- * @param object $tax Taxonomy object
- * @return object object with all the labels as member variables
+ * @since 4.3.0 Added the `no_terms` label.
+ *
+ * @param object $tax Taxonomy object.
+ * @return object object with all the labels as member variables.
*/
-
function get_taxonomy_labels( $tax ) {
$tax->labels = (array) $tax->labels;
'add_or_remove_items' => array( __( 'Add or remove tags' ), null ),
'choose_from_most_used' => array( __( 'Choose from the most used tags' ), null ),
'not_found' => array( __( 'No tags found.' ), __( 'No categories found.' ) ),
+ 'no_terms' => array( __( 'No tags' ), __( 'No categories' ) ),
);
$nohier_vs_hier_defaults['menu_name'] = $nohier_vs_hier_defaults['name'];
* Add an already registered taxonomy to an object type.
*
* @since 3.0.0
- * @uses $wp_taxonomies Modifies taxonomy object
*
- * @param string $taxonomy Name of taxonomy object
- * @param string $object_type Name of the object type
- * @return bool True if successful, false if not
+ * @global array $wp_taxonomies The registered taxonomies.
+ *
+ * @param string $taxonomy Name of taxonomy object.
+ * @param string $object_type Name of the object type.
+ * @return bool True if successful, false if not.
*/
function register_taxonomy_for_object_type( $taxonomy, $object_type) {
global $wp_taxonomies;
if ( ! in_array( $object_type, $wp_taxonomies[$taxonomy]->object_type ) )
$wp_taxonomies[$taxonomy]->object_type[] = $object_type;
+ // Filter out empties.
+ $wp_taxonomies[ $taxonomy ]->object_type = array_filter( $wp_taxonomies[ $taxonomy ]->object_type );
+
return true;
}
*
* @since 3.7.0
*
+ * @global array $wp_taxonomies The registered taxonomies.
+ *
* @param string $taxonomy Name of taxonomy object.
* @param string $object_type Name of the object type.
* @return bool True if successful, false if not.
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @param int|array $term_ids Term id or array of term ids of terms that will be used
- * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names
- * @param array|string $args Change the order of the object_ids, either ASC or DESC
- * @return WP_Error|array If the taxonomy does not exist, then WP_Error will be returned. On success
+ * @param int|array $term_ids Term id or array of term ids of terms that will be used.
+ * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names.
+ * @param array|string $args Change the order of the object_ids, either ASC or DESC.
+ * @return WP_Error|array If the taxonomy does not exist, then WP_Error will be returned. On success.
* the array can be empty meaning that there are no $object_ids found or it will return the $object_ids found.
*/
function get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
*
* @see WP_Tax_Query
*
- * @param array $tax_query A compact tax query
+ * @param array $tax_query A compact tax query
* @param string $primary_table
* @param string $primary_id_column
* @return array
/**
* Class for generating SQL clauses that filter a primary query according to object taxonomy terms.
*
- * `WP_Tax_Query` is a helper that allows primary query classes, such as {@see WP_Query}, to filter
+ * `WP_Tax_Query` is a helper that allows primary query classes, such as WP_Query, to filter
* their results by object metadata, by generating `JOIN` and `WHERE` subclauses to be attached
* to the primary SQL query string.
*
* Standard response when the query should not return any rows.
*
* @since 3.2.0
+ *
+ * @static
* @access private
* @var string
*/
* Terms and taxonomies fetched by this query.
*
* We store this data in a flat array because they are referenced in a
- * number of places by {@see WP_Query}.
+ * number of places by WP_Query.
*
* @since 4.1.0
* @access public
* determined, by process of elimination, to be a higher-order query.
*
* @since 4.1.0
+ *
+ * @static
* @access protected
*
* @param array $query Tax query arguments.
* Generates SQL clauses to be appended to a main query.
*
* @since 3.1.0
+ *
+ * @static
* @access public
*
* @param string $primary_table Database table where the object being filtered is stored (eg wp_users).
/**
* Generate SQL clauses to be appended to a main query.
*
- * Called by the public {@see WP_Tax_Query::get_sql()}, this method
+ * Called by the public WP_Tax_Query::get_sql(), this method
* is abstracted out to maintain parity with the other Query classes.
*
* @since 4.1.0
* @since 4.1.0
* @access public
*
- * @param array $clause Query clause, passed by reference
+ * @global wpdb $wpdb The WordPress database abstraction object.
+ *
+ * @param array $clause Query clause, passed by reference.
* @param array $parent_query Parent query array.
* @return array {
* Array containing JOIN and WHERE SQL clauses to append to a first-order query.
'join' => array(),
);
- $join = '';
+ $join = $where = '';
$this->clean_query( $clause );
* An existing alias is compatible if (a) it is a sibling of `$clause`
* (ie, it's under the scope of the same relation), and (b) the combination
* of operator and relation between the clauses allows for a shared table
- * join. In the case of {@see WP_Tax_Query}, this only applies to 'IN'
+ * join. In the case of WP_Tax_Query, this only applies to 'IN'
* clauses that are connected by the relation 'OR'.
*
* @since 4.1.0
*
* @param array $clause Query clause.
* @param array $parent_query Parent query of $clause.
- * @return string|bool Table alias if found, otherwise false.
+ * @return string|false Table alias if found, otherwise false.
*/
protected function find_compatible_table_alias( $clause, $parent_query ) {
$alias = false;
*
* @since 3.2.0
*
+ * @global wpdb $wpdb The WordPress database abstraction object.
+ *
* @param array &$query The single query.
* @param string $resulting_field The resulting field. Accepts 'slug', 'name', 'term_taxonomy_id',
- * or 'term_id'. Default: 'term_id'.
+ * or 'term_id'. Default 'term_id'.
*/
public function transform_query( &$query, $resulting_field ) {
global $wpdb;
* term object, and the taxonomy name as parameters. Both hooks are expected to
* return a Term object.
*
- * 'get_term' hook - Takes two parameters the term Object and the taxonomy name.
+ * {@see 'get_term'} hook - Takes two parameters the term Object and the taxonomy name.
* Must return term object. Used in get_term() as a catch-all filter for every
* $term.
*
- * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy
+ * {@see 'get_$taxonomy'} hook - Takes two parameters the term Object and the taxonomy
* name. Must return term object. $taxonomy will be the taxonomy name, so for
* example, if 'category', it would be 'get_category' as the filter name. Useful
* for custom taxonomies or plugging into default taxonomies.
*
+ * @todo Better formatting for DocBlock
+ *
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
* @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
*
- * @param int|object $term If integer, will get from database. If object will apply filters and return $term.
- * @param string $taxonomy Taxonomy name that $term is part of.
- * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
- * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
- * @return mixed|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not
+ * @param int|object $term If integer, will get from database. If object will apply filters and return $term.
+ * @param string $taxonomy Taxonomy name that $term is part of.
+ * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
+ * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
+ * @return object|array|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not
* exist then WP_Error will be returned.
*/
function get_term($term, $taxonomy, $output = OBJECT, $filter = 'raw') {
global $wpdb;
- if ( empty($term) ) {
- $error = new WP_Error('invalid_term', __('Empty Term'));
- return $error;
+ if ( empty( $term ) ) {
+ return new WP_Error( 'invalid_term', __( 'Empty Term' ) );
}
- if ( ! taxonomy_exists($taxonomy) ) {
- $error = new WP_Error('invalid_taxonomy', __('Invalid taxonomy'));
- return $error;
+ if ( ! taxonomy_exists( $taxonomy ) ) {
+ return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) );
}
if ( is_object($term) && empty($term->filter) ) {
* If $value does not exist, the return value will be false. If $taxonomy exists
* and $field and $value combinations exist, the Term will be returned.
*
+ * @todo Better formatting for DocBlock.
+ *
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
* @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
*
- * @param string $field Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'
- * @param string|int $value Search for this term value
- * @param string $taxonomy Taxonomy Name
- * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
- * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
- * @return mixed Term Row from database. Will return false if $taxonomy does not exist or $term was not found.
+ * @param string $field Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'
+ * @param string|int $value Search for this term value
+ * @param string $taxonomy Taxonomy Name
+ * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
+ * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
+ * @return object|array|null|WP_Error|false Term Row from database.
+ * Will return false if $taxonomy does not exist or $term was not found.
*/
function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw') {
global $wpdb;
*
* @since 2.3.0
*
- * @global wpdb $wpdb WordPress database abstraction object.
- *
- * @param string $term_id ID of Term to get children
- * @param string $taxonomy Taxonomy Name
- * @return array|WP_Error List of Term IDs. WP_Error returned if $taxonomy does not exist
+ * @param string $term_id ID of Term to get children.
+ * @param string $taxonomy Taxonomy Name.
+ * @return array|WP_Error List of Term IDs. WP_Error returned if `$taxonomy` does not exist.
*/
function get_term_children( $term_id, $taxonomy ) {
if ( ! taxonomy_exists($taxonomy) )
*
* @since 2.3.0
*
- * @param string $field Term field to fetch
- * @param int $term Term ID
- * @param string $taxonomy Taxonomy Name
- * @param string $context Optional, default is display. Look at sanitize_term_field() for available options.
- * @return mixed Will return an empty string if $term is not an object or if $field is not set in $term.
+ * @param string $field Term field to fetch.
+ * @param int $term Term ID.
+ * @param string $taxonomy Taxonomy Name.
+ * @param string $context Optional, default is display. Look at sanitize_term_field() for available options.
+ * @return string|int|null|WP_Error Will return an empty string if $term is not an object or if $field is not set in $term.
*/
function get_term_field( $field, $term, $taxonomy, $context = 'display' ) {
$term = (int) $term;
*
* @since 2.3.0
*
- * @param int|object $id Term ID or Object
- * @param string $taxonomy Taxonomy Name
- * @return mixed|null|WP_Error Will return empty string if $term is not an object.
+ * @param int|object $id Term ID or object.
+ * @param string $taxonomy Taxonomy name.
+ * @return string|int|null|WP_Error Will return empty string if $term is not an object.
*/
function get_term_to_edit( $id, $taxonomy ) {
$term = get_term( $id, $taxonomy );
* You can fully inject any customizations to the query before it is sent, as
* well as control the output with a filter.
*
- * The 'get_terms' filter will be called when the cache has the term and will
+ * 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 'list_terms_exclusions' filter passes the compiled exclusions along with
+ * The {@see 'list_terms_exclusions'} filter passes the compiled exclusions along with
* the $args.
*
- * The 'get_terms_orderby' filter passes the ORDER BY clause for the query
+ * 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.
*
- * @global wpdb $wpdb WordPress database abstraction object.
+ * @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 {
* @type string $cache_domain Unique cache key to be produced when this query is stored in an
* object cache. Default is 'core'.
* }
- * @return array|WP_Error List of Term Objects and their children. Will return WP_Error, if any of $taxonomies
+ * @return array|int|WP_Error List of Term Objects and their children. Will return WP_Error, if any of $taxonomies
* do not exist.
*/
function get_terms( $taxonomies, $args = '' ) {
foreach ( $taxonomies as $taxonomy ) {
if ( ! taxonomy_exists($taxonomy) ) {
- $error = new WP_Error('invalid_taxonomy', __('Invalid taxonomy'));
- return $error;
+ return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) );
}
}
*
* @since 3.1.0
*
- * @param array $args An array of arguments.
+ * @param array $args An array of get_term() arguments.
* @param array $taxonomies An array of taxonomies.
*/
$args = apply_filters( 'get_terms_args', $args, $taxonomies );
}
}
- // $args can be whatever, only use the args defined in defaults to compute the key
+ // $args can be whatever, only use the args defined in defaults to compute the key.
$filter_key = ( has_filter('list_terms_exclusions') ) ? serialize($GLOBALS['wp_filter']['list_terms_exclusions']) : '';
$key = md5( serialize( wp_array_slice_assoc( $args, array_keys( $defaults ) ) ) . serialize( $taxonomies ) . $filter_key );
$last_changed = wp_cache_get( 'last_changed', 'terms' );
*
* @param array $cache Cached array of terms for the given taxonomy.
* @param array $taxonomies An array of taxonomies.
- * @param array $args An array of arguments to get terms.
+ * @param array $args An array of get_terms() arguments.
*/
- $cache = apply_filters( 'get_terms', $cache, $taxonomies, $args );
- return $cache;
+ return apply_filters( 'get_terms', $cache, $taxonomies, $args );
}
$_orderby = strtolower( $args['orderby'] );
} 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 string $orderby `ORDERBY` clause of the terms query.
* @param array $args An array of terms query arguments.
* @param array $taxonomies An array of taxonomies.
*/
*
* @since 2.3.0
*
- * @param string $exclusions NOT IN clause of the terms query.
+ * @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.
*/
}
if ( ! empty( $args['name'] ) ) {
- if ( is_array( $args['name'] ) ) {
- $name = array_map( 'sanitize_text_field', $args['name'] );
- $where .= " AND t.name IN ('" . implode( "', '", array_map( 'esc_sql', $name ) ) . "')";
- } else {
- $name = sanitize_text_field( $args['name'] );
- $where .= $wpdb->prepare( " AND t.name = %s", $name );
+ $names = (array) $args['name'];
+ foreach ( $names as &$_name ) {
+ $_name = sanitize_term_field( 'name', $_name, 0, reset( $taxonomies ), 'db' );
}
+
+ $where .= " AND t.name IN ('" . implode( "', '", array_map( 'esc_sql', $names ) ) . "')";
}
if ( ! empty( $args['slug'] ) ) {
$number = $args['number'];
$offset = $args['offset'];
- // don't limit the query results when we have to descend the family tree
+ // 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;
* @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' ] : '';
$query = "SELECT $fields FROM $wpdb->terms AS t $join WHERE $where $orderby $order $limits";
if ( 'count' == $_fields ) {
- $term_count = $wpdb->get_var($query);
- return $term_count;
+ return $wpdb->get_var( $query );
}
$terms = $wpdb->get_results($query);
wp_cache_add( $cache_key, array(), 'terms', DAY_IN_SECONDS );
/** This filter is documented in wp-includes/taxonomy.php */
- $terms = apply_filters( 'get_terms', array(), $taxonomies, $args );
- return $terms;
+ return apply_filters( 'get_terms', array(), $taxonomies, $args );
}
if ( $child_of ) {
}
}
- // It really is empty
+ // It really is empty.
unset($terms[$k]);
}
}
wp_cache_add( $cache_key, $terms, 'terms', DAY_IN_SECONDS );
/** This filter is documented in wp-includes/taxonomy */
- $terms = apply_filters( 'get_terms', $terms, $taxonomies, $args );
- return $terms;
+ return apply_filters( 'get_terms', $terms, $taxonomies, $args );
}
/**
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @param int|string $term The term to check
- * @param string $taxonomy The taxonomy name to use
- * @param int $parent Optional. ID of parent term under which to confine the exists search.
+ * @param int|string $term The term to check
+ * @param string $taxonomy The taxonomy name to use
+ * @param int $parent Optional. ID of parent term under which to confine the exists search.
* @return mixed Returns null if the term does not exist. Returns the term ID
* if no taxonomy is specified and the term ID exists. Returns
* an array of the term ID and the term taxonomy ID the taxonomy
*
* @since 3.4.0
*
- * @param int|object $term1 ID or object to check if this is the parent term.
- * @param int|object $term2 The child term.
- * @param string $taxonomy Taxonomy name that $term1 and $term2 belong to.
- * @return bool Whether $term2 is child of $term1
+ * @param int|object $term1 ID or object to check if this is the parent term.
+ * @param int|object $term2 The child term.
+ * @param string $taxonomy Taxonomy name that $term1 and `$term2` belong to.
+ * @return bool Whether `$term2` is a child of `$term1`.
*/
function term_is_ancestor_of( $term1, $term2, $taxonomy ) {
if ( ! isset( $term1->term_id ) )
*
* @since 2.3.0
*
- * @param array|object $term The term to check
- * @param string $taxonomy The taxonomy name to use
- * @param string $context Default is 'display'.
- * @return array|object Term with all fields sanitized
+ * @param array|object $term The term to check.
+ * @param string $taxonomy The taxonomy name to use.
+ * @param string $context Optional. Context in which to sanitize the term. Accepts 'edit', 'db',
+ * 'display', 'attribute', or 'js'. Default 'display'.
+ * @return array|object Term with all fields sanitized.
*/
function sanitize_term($term, $taxonomy, $context = 'display') {
-
$fields = array( 'term_id', 'name', 'description', 'slug', 'count', 'parent', 'term_group', 'term_taxonomy_id', 'object_id' );
$do_object = is_object( $term );
*
* @since 2.3.0
*
- * @global wpdb $wpdb WordPress database abstraction object.
- *
- * @param string $field Term field to sanitize
- * @param string $value Search for this term value
- * @param int $term_id Term ID
- * @param string $taxonomy Taxonomy Name
- * @param string $context Either edit, db, display, attribute, or js.
- * @return mixed sanitized field
+ * @param string $field Term field to sanitize.
+ * @param string $value Search for this term value.
+ * @param int $term_id Term ID.
+ * @param string $taxonomy Taxonomy Name.
+ * @param string $context Context in which to sanitize the term field. Accepts 'edit', 'db', 'display',
+ * 'attribute', or 'js'.
+ * @return mixed Sanitized field.
*/
function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) {
$int_fields = array( 'parent', 'term_id', 'count', 'term_group', 'term_taxonomy_id', 'object_id' );
* @param int $term_id Term ID.
*/
$value = apply_filters( "edit_{$taxonomy}_{$field}", $value, $term_id );
+
if ( 'description' == $field )
$value = esc_html($value); // textarea_escaped
else
* @param mixed $value Value of the taxonomy field.
*/
$value = apply_filters( "pre_{$taxonomy}_{$field}", $value );
+
// Back compat filters
if ( 'slug' == $field ) {
/**
/**
* Filter the taxonomy field for use in RSS.
*
- * The dynamic portions of the hook name, `$taxonomy`, and $field, refer
+ * The dynamic portions of the hook name, `$taxonomy`, and `$field`, refer
* to the taxonomy slug and field name, respectively.
*
* @since 2.3.0
/**
* Filter the taxonomy field sanitized for display.
*
- * The dynamic portions of the filter name, `$taxonomy`, and $field, refer
+ * The dynamic portions of the filter name, `$taxonomy`, and `$field`, refer
* to the taxonomy slug and taxonomy field, respectively.
*
* @since 2.3.0
*
* Default $args is 'hide_empty' which can be 'hide_empty=true' or array('hide_empty' => true).
*
+ * @todo Document $args as a hash notation.
+ *
* @since 2.3.0
*
- * @param string $taxonomy Taxonomy name
- * @param array|string $args Overwrite defaults. See get_terms()
- * @return int|WP_Error How many terms are in $taxonomy. WP_Error if $taxonomy does not exist.
+ * @param string $taxonomy Taxonomy name
+ * @param array|string $args Overwrite defaults. See get_terms()
+ * @return array|int|WP_Error How many terms are in $taxonomy. WP_Error if $taxonomy does not exist.
*/
function wp_count_terms( $taxonomy, $args = array() ) {
$defaults = array('hide_empty' => false);
*
* @since 2.3.0
*
- * @param int $object_id The term Object Id that refers to the term
+ * @param int $object_id The term Object Id that refers to the term.
* @param string|array $taxonomies List of Taxonomy Names or single Taxonomy name.
*/
function wp_delete_object_term_relationships( $object_id, $taxonomies ) {
* If the term is a parent of other terms, then the children will be updated to
* that term's parent.
*
- * The $args 'default' will only override the terms found, if there is only one
+ * The `$args` 'default' will only override the terms found, if there is only one
* term found. Any other and the found terms are used.
*
* The $args 'force_default' will force the term supplied as default to be
* assigned even if the object was not going to be termless
*
+ * @todo Document $args as a hash notation.
+ *
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @param int $term Term ID
- * @param string $taxonomy Taxonomy Name
- * @param array|string $args Optional. Change 'default' term id and override found term ids.
- * @return bool|WP_Error Returns false if not term; true if completes delete action.
+ * @param int $term Term ID.
+ * @param string $taxonomy Taxonomy Name.
+ * @param array|string $args Optional. Change 'default' term id and override found term ids.
+ * @return bool|int|WP_Error Returns false if not term; true if completes delete action.
*/
function wp_delete_term( $term, $taxonomy, $args = array() ) {
global $wpdb;
* @param array $edit_tt_ids An array of term taxonomy IDs for the given term.
*/
do_action( 'edit_term_taxonomies', $edit_tt_ids );
+
$wpdb->update( $wpdb->term_taxonomy, compact( 'parent' ), array( 'parent' => $term_obj->term_id) + compact( 'taxonomy' ) );
// Clean the cache for all child terms.
wp_set_object_terms($object, $terms, $taxonomy);
}
- // Clean the relationship caches for all object types using this term
+ // Clean the relationship caches for all object types using this term.
$tax_object = get_taxonomy( $taxonomy );
foreach ( $tax_object->object_type as $object_type )
clean_object_term_cache( $objects, $object_type );
* @param int $term Term ID.
* @param int $tt_id Term taxonomy ID.
* @param mixed $deleted_term Copy of the already-deleted term, in the form specified
- * by the parent function. {@see WP_Error} otherwise.
+ * by the parent function. WP_Error otherwise.
*/
do_action( "delete_$taxonomy", $term, $tt_id, $deleted_term );
* @since 2.0.0
*
* @param int $cat_ID
- * @return mixed Returns true if completes delete action; false if term doesn't exist;
+ * @return bool|int|WP_Error Returns true if completes delete action; false if term doesn't exist;
* Zero on attempted deletion of default Category; WP_Error object is also a possibility.
*/
function wp_delete_category( $cat_ID ) {
if ( in_array( $orderby, array( 'term_id', 'name', 'slug', 'term_group' ) ) ) {
$orderby = "t.$orderby";
- } else if ( in_array( $orderby, array( 'count', 'parent', 'taxonomy', 'term_taxonomy_id' ) ) ) {
+ } elseif ( in_array( $orderby, array( 'count', 'parent', 'taxonomy', 'term_taxonomy_id' ) ) ) {
$orderby = "tt.$orderby";
- } else if ( 'term_order' === $orderby ) {
+ } elseif ( 'term_order' === $orderby ) {
$orderby = 'tr.term_order';
- } else if ( 'none' === $orderby ) {
+ } elseif ( 'none' === $orderby ) {
$orderby = '';
$order = '';
} else {
}
if ( $existing_term ) {
- return new WP_Error( 'term_exists', __( 'A term with the name already exists with this parent.' ), $existing_term->term_id );
+ return new WP_Error( 'term_exists', __( 'A term with the name provided already exists with this parent.' ), $existing_term->term_id );
}
} else {
- return new WP_Error( 'term_exists', __( 'A term with the name already exists in this taxonomy.' ), $name_match->term_id );
+ return new WP_Error( 'term_exists', __( 'A term with the name provided already exists in this taxonomy.' ), $name_match->term_id );
}
}
}
* Fires after a new term is created, and after the term cache has been cleaned.
*
* @since 2.3.0
+ *
+ * @param int $term_id Term ID.
+ * @param int $tt_id Term taxonomy ID.
+ * @param string $taxonomy Taxonomy slug.
*/
- do_action( "created_term", $term_id, $tt_id, $taxonomy );
+ do_action( 'created_term', $term_id, $tt_id, $taxonomy );
/**
* Fires after a new term in a specific taxonomy is created, and after the term
* cache has been cleaned.
*
+ * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
+ *
* @since 2.3.0
*
* @param int $term_id Term ID.
*
* @since 2.3.0
*
+ * @global wpdb $wpdb The WordPress database abstraction object.
+ *
* @param int $object_id The object to relate to.
* @param array|int|string $terms A single term slug, single term id, or array of either term slugs or ids.
* Will replace all existing related terms in this taxonomy.
*
* @since 3.6.0
*
- * @param int $object_id The ID of the object to which the terms will be added.
- * @param array|int|string $terms The slug(s) or ID(s) of the term(s) to add.
- * @param array|string $taxonomy Taxonomy name.
+ * @param int $object_id The ID of the object to which the terms will be added.
+ * @param array|int|string $terms The slug(s) or ID(s) of the term(s) to add.
+ * @param array|string $taxonomy Taxonomy name.
* @return array|WP_Error Affected Term IDs
*/
function wp_add_object_terms( $object_id, $terms, $taxonomy ) {
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @param int $object_id The ID of the object from which the terms will be removed.
- * @param array|int|string $terms The slug(s) or ID(s) of the term(s) to remove.
- * @param array|string $taxonomy Taxonomy name.
+ * @param int $object_id The ID of the object from which the terms will be removed.
+ * @param array|int|string $terms The slug(s) or ID(s) of the term(s) to remove.
+ * @param array|string $taxonomy Taxonomy name.
* @return bool|WP_Error True on success, false or WP_Error on failure.
*/
function wp_remove_object_terms( $object_id, $terms, $taxonomy ) {
* @param array $tt_ids An array of term taxonomy IDs.
*/
do_action( 'deleted_term_relationships', $object_id, $tt_ids );
+
wp_update_term_count( $tt_ids, $taxonomy );
return (bool) $deleted;
/**
* Will make slug unique, if it isn't already.
*
- * The $slug has to be unique global to every taxonomy, meaning that one
+ * The `$slug` has to be unique global to every taxonomy, meaning that one
* taxonomy term can't have a matching slug with another taxonomy term. Each
* slug has to be globally unique for every taxonomy.
*
* If that still doesn't return an unique slug, then it try to append a number
* until it finds a number that is truly unique.
*
- * The only purpose for $term is for appending a parent, if one exists.
+ * The only purpose for `$term` is for appending a parent, if one exists.
*
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @param string $slug The string that will be tried for a unique slug
- * @param object $term The term object that the $slug will belong too
+ * @param string $slug The string that will be tried for a unique slug.
+ * @param object $term The term object that the `$slug` will belong to.
* @return string Will return a true unique slug.
*/
-function wp_unique_term_slug($slug, $term) {
+function wp_unique_term_slug( $slug, $term ) {
global $wpdb;
- if ( ! term_exists( $slug ) )
- return $slug;
+ $needs_suffix = true;
+ $original_slug = $slug;
// As of 4.1, duplicate slugs are allowed as long as they're in different taxonomies.
- if ( get_option( 'db_version' ) >= 30133 && ! get_term_by( 'slug', $slug, $term->taxonomy ) ) {
- return $slug;
+ if ( ! term_exists( $slug ) || get_option( 'db_version' ) >= 30133 && ! get_term_by( 'slug', $slug, $term->taxonomy ) ) {
+ $needs_suffix = false;
}
- // If the taxonomy supports hierarchy and the term has a parent, make the slug unique
- // by incorporating parent slugs.
- if ( is_taxonomy_hierarchical($term->taxonomy) && !empty($term->parent) ) {
+ /*
+ * If the taxonomy supports hierarchy and the term has a parent, make the slug unique
+ * by incorporating parent slugs.
+ */
+ $parent_suffix = '';
+ if ( $needs_suffix && is_taxonomy_hierarchical( $term->taxonomy ) && ! empty( $term->parent ) ) {
$the_parent = $term->parent;
while ( ! empty($the_parent) ) {
$parent_term = get_term($the_parent, $term->taxonomy);
if ( is_wp_error($parent_term) || empty($parent_term) )
break;
- $slug .= '-' . $parent_term->slug;
- if ( ! term_exists( $slug ) )
- return $slug;
+ $parent_suffix .= '-' . $parent_term->slug;
+ if ( ! term_exists( $slug . $parent_suffix ) ) {
+ break;
+ }
if ( empty($parent_term->parent) )
break;
}
// If we didn't get a unique slug, try appending a number to make it unique.
- if ( ! empty( $term->term_id ) )
- $query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s AND term_id != %d", $slug, $term->term_id );
- else
- $query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $slug );
- if ( $wpdb->get_var( $query ) ) {
- $num = 2;
- do {
- $alt_slug = $slug . "-$num";
- $num++;
- $slug_check = $wpdb->get_var( $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $alt_slug ) );
- } while ( $slug_check );
- $slug = $alt_slug;
+ /**
+ * Filter whether the proposed unique term slug is bad.
+ *
+ * @since 4.3.0
+ *
+ * @param bool $needs_suffix Whether the slug needs to be made unique with a suffix.
+ * @param string $slug The slug.
+ * @param object $term Term object.
+ */
+ if ( apply_filters( 'wp_unique_term_slug_is_bad_slug', $needs_suffix, $slug, $term ) ) {
+ if ( $parent_suffix ) {
+ $slug .= $parent_suffix;
+ } else {
+ if ( ! empty( $term->term_id ) )
+ $query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s AND term_id != %d", $slug, $term->term_id );
+ else
+ $query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $slug );
+
+ if ( $wpdb->get_var( $query ) ) {
+ $num = 2;
+ do {
+ $alt_slug = $slug . "-$num";
+ $num++;
+ $slug_check = $wpdb->get_var( $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $alt_slug ) );
+ } while ( $slug_check );
+ $slug = $alt_slug;
+ }
+ }
}
- return $slug;
+ /**
+ * Filter the unique term slug.
+ *
+ * @since 4.3.0
+ *
+ * @param string $slug Unique term slug.
+ * @param object $term Term object.
+ * @param string $original_slug Slug originally passed to the function for testing.
+ */
+ return apply_filters( 'wp_unique_term_slug', $slug, $term, $original_slug );
}
/**
* a WP_Error will be passed back. If you don't pass any slug, then a unique one
* will be created for you.
*
- * For what can be overrode in $args, check the term scheme can contain and stay
+ * For what can be overrode in `$args`, check the term scheme can contain and stay
* away from the term keys.
*
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @param int $term_id The ID of the term
- * @param string $taxonomy The context in which to relate the term to the object.
- * @param array|string $args Overwrite term field values
+ * @param int $term_id The ID of the term
+ * @param string $taxonomy The context in which to relate the term to the object.
+ * @param array|string $args Optional. Array of get_terms() arguments. Default empty array.
* @return array|WP_Error Returns Term ID and Taxonomy Term ID
*/
function wp_update_term( $term_id, $taxonomy, $args = array() ) {
* @param string $taxonomy Taxonomy slug.
*/
do_action( 'edit_term_taxonomy', $tt_id, $taxonomy );
+
$wpdb->update( $wpdb->term_taxonomy, compact( 'term_id', 'taxonomy', 'description', 'parent' ), array( 'term_taxonomy_id' => $tt_id ) );
/**
*/
do_action( 'edited_term_taxonomy', $tt_id, $taxonomy );
- // Clean the relationship caches for all object types using this term
+ // Clean the relationship caches for all object types using this term.
$objects = $wpdb->get_col( $wpdb->prepare( "SELECT object_id FROM $wpdb->term_relationships WHERE term_taxonomy_id = %d", $tt_id ) );
$tax_object = get_taxonomy( $taxonomy );
foreach ( $tax_object->object_type as $object_type ) {
*
* @since 2.5.0
*
+ * @staticvar bool $_defer
+ *
* @param bool $defer Optional. Enable if true, disable if false.
* @return bool Whether term counting is enabled or disabled.
*/
*
* @since 2.3.0
*
- * @global wpdb $wpdb WordPress database abstraction object.
+ * @staticvar array $_deferred
*
- * @param int|array $terms The term_taxonomy_id of the terms
- * @param string $taxonomy The context of the term.
+ * @param int|array $terms The term_taxonomy_id of the terms.
+ * @param string $taxonomy The context of the term.
* @return bool If no terms will return false, and if successful will return true.
*/
function wp_update_term_count( $terms, $taxonomy, $do_deferred=false ) {
*
* @since 2.5.0
*
- * @param array $terms The term_taxonomy_id of terms to update.
+ * @param array $terms The term_taxonomy_id of terms to update.
* @param string $taxonomy The context of the term.
- * @return bool Always true when complete.
+ * @return true Always true when complete.
*/
function wp_update_term_count_now( $terms, $taxonomy ) {
$terms = array_map('intval', $terms);
/**
* Removes the taxonomy relationship to terms from the cache.
*
- * Will remove the entire taxonomy relationship containing term $object_id. The
- * term IDs have to exist within the taxonomy $object_type for the deletion to
+ * Will remove the entire taxonomy relationship containing term `$object_id`. The
+ * term IDs have to exist within the taxonomy `$object_type` for the deletion to
* take place.
*
* @since 2.3.0
*
- * @see get_object_taxonomies() for more on $object_type
+ * @see get_object_taxonomies() for more on $object_type.
*
- * @param int|array $object_ids Single or list of term object ID(s)
- * @param array|string $object_type The taxonomy object type
+ * @param int|array $object_ids Single or list of term object ID(s).
+ * @param array|string $object_type The taxonomy object type.
*/
function clean_object_term_cache($object_ids, $object_type) {
if ( !is_array($object_ids) )
* @since 2.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
+ * @global bool $_wp_suspend_cache_invalidation
*
- * @param int|array $ids Single or list of Term IDs
- * @param string $taxonomy Can be empty and will assume tt_ids, else will use for context.
- * @param bool $clean_taxonomy Whether to clean taxonomy wide caches (true), or just individual term object caches (false). Default is true.
+ * @param int|array $ids Single or list of Term IDs.
+ * @param string $taxonomy Optional. Can be empty and will assume `tt_ids`, else will use for context.
+ * Default empty.
+ * @param bool $clean_taxonomy Optional. Whether to clean taxonomy wide caches (true), or just individual
+ * term object caches (false). Default true.
*/
function clean_term_cache($ids, $taxonomy = '', $clean_taxonomy = true) {
- global $wpdb;
+ global $wpdb, $_wp_suspend_cache_invalidation;
+
+ if ( ! empty( $_wp_suspend_cache_invalidation ) ) {
+ return;
+ }
if ( !is_array($ids) )
$ids = array($ids);
*
* @since 2.3.0
*
- * @param int $id Term object ID
- * @param string $taxonomy Taxonomy Name
- * @return bool|array Empty array if $terms found, but not $taxonomy. False if nothing is in cache for $taxonomy and $id.
+ * @param int $id Term object ID.
+ * @param string $taxonomy Taxonomy name.
+ * @return bool|mixed Empty array if $terms found, but not `$taxonomy`. False if nothing is in cache
+ * for `$taxonomy` and `$id`.
*/
-function get_object_term_cache($id, $taxonomy) {
- $cache = wp_cache_get($id, "{$taxonomy}_relationships");
- return $cache;
+function get_object_term_cache( $id, $taxonomy ) {
+ return wp_cache_get( $id, "{$taxonomy}_relationships" );
}
/**
*
* @since 2.3.0
*
- * @param string|array $object_ids Comma-separated list or array of term object IDs..
+ * @param string|array $object_ids Comma-separated list or array of term object IDs.
* @param array|string $object_type The taxonomy object type.
- * @return null|false Null if `$object_ids` is empty, false if all of the terms in
- * `$object_ids` are already cached.
+ * @return void|false False if all of the terms in `$object_ids` are already cached.
*/
function update_object_term_cache($object_ids, $object_type) {
if ( empty($object_ids) )
*
* @since 2.3.0
*
- * @param array $terms List of Term objects to change
- * @param string $taxonomy Optional. Update Term to this taxonomy in cache
+ * @param array $terms List of term objects to change.
+ * @param string $taxonomy Optional. Update Term to this taxonomy in cache. Default empty.
*/
-function update_term_cache($terms, $taxonomy = '') {
+function update_term_cache( $terms, $taxonomy = '' ) {
foreach ( (array) $terms as $term ) {
$term_taxonomy = $taxonomy;
if ( empty($term_taxonomy) )
/**
* Retrieves children of taxonomy as Term IDs.
*
- * @access private
+ * @ignore
* @since 2.3.0
*
- * @param string $taxonomy Taxonomy Name
+ * @param string $taxonomy Taxonomy name.
* @return array Empty if $taxonomy isn't hierarchical or returns children as Term IDs.
*/
-function _get_term_hierarchy($taxonomy) {
+function _get_term_hierarchy( $taxonomy ) {
if ( !is_taxonomy_hierarchical($taxonomy) )
return array();
$children = get_option("{$taxonomy}_children");
/**
* Get the subset of $terms that are descendants of $term_id.
*
- * If $terms is an array of objects, then _get_term_children returns an array of objects.
- * If $terms is an array of IDs, then _get_term_children returns an array of IDs.
+ * If `$terms` is an array of objects, then _get_term_children() returns an array of objects.
+ * If `$terms` is an array of IDs, then _get_term_children() returns an array of IDs.
*
* @access private
* @since 2.3.0
*
- * @param int $term_id The ancestor term: all returned terms should be descendants of $term_id.
+ * @param int $term_id The ancestor term: all returned terms should be descendants of `$term_id`.
* @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 The taxonomy which determines the hierarchy of the terms.
- * @param array $ancestors Term ancestors that have already been identified. Passed by reference, to keep track of
- * found terms when recursing the hierarchy. The array of located ancestors is used to prevent
- * infinite recursion loops.
- * @return array The subset of $terms that are descendants of $term_id.
+ * @param array $ancestors Optional. Term ancestors that have already been identified. Passed by reference, to keep
+ * track of found terms when recursing the hierarchy. The array of located ancestors is used
+ * to prevent infinite recursion loops. For performance, `term_ids` are used as array keys,
+ * with 1 as value. Default empty array.
+ * @return array|WP_Error The subset of $terms that are descendants of $term_id.
*/
function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array() ) {
$empty_array = array();
// Include the term itself in the ancestors array, so we can properly detect when a loop has occurred.
if ( empty( $ancestors ) ) {
- $ancestors[] = $term_id;
+ $ancestors[ $term_id ] = 1;
}
foreach ( (array) $terms as $term ) {
}
// Don't recurse if we've already identified the term as a child - this indicates a loop.
- if ( in_array( $term->term_id, $ancestors ) ) {
+ if ( isset( $ancestors[ $term->term_id ] ) ) {
continue;
}
if ( !isset($has_children[$term->term_id]) )
continue;
- if ( $use_id ) {
- $ancestors = array_merge( $ancestors, $term_list );
- } else {
- $ancestors = array_merge( $ancestors, wp_list_pluck( $term_list, 'term_id' ) );
- }
+ $ancestors[ $term->term_id ] = 1;
if ( $children = _get_term_children( $term->term_id, $terms, $taxonomy, $ancestors) )
$term_list = array_merge($term_list, $children);
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @param array $terms List of Term IDs
- * @param string $taxonomy Term Context
- * @return null Will break from function if conditions are not met.
+ * @param array $terms List of term IDs, passed by reference.
+ * @param string $taxonomy Term context.
*/
-function _pad_term_counts(&$terms, $taxonomy) {
+function _pad_term_counts( &$terms, $taxonomy ) {
global $wpdb;
// This function only works for hierarchical taxonomies like post categories.
$term_ids[$term->term_taxonomy_id] = $term->term_id;
}
- // Get the object and term ids and stick them in a lookup table
+ // Get the object and term ids and stick them in a lookup table.
$tax_obj = get_taxonomy($taxonomy);
$object_types = esc_sql($tax_obj->object_type);
$results = $wpdb->get_results("SELECT object_id, term_taxonomy_id FROM $wpdb->term_relationships INNER JOIN $wpdb->posts ON object_id = ID WHERE term_taxonomy_id IN (" . implode(',', array_keys($term_ids)) . ") AND post_type IN ('" . implode("', '", $object_types) . "') AND post_status = 'publish'");
$term_items[$id][$row->object_id] = isset($term_items[$id][$row->object_id]) ? ++$term_items[$id][$row->object_id] : 1;
}
- // Touch every ancestor's lookup row for each post in each term
+ // Touch every ancestor's lookup row for each post in each term.
foreach ( $term_ids as $term_id ) {
$child = $term_id;
$ancestors = array();
}
}
- // Transfer the touched cells
+ // Transfer the touched cells.
foreach ( (array) $term_items as $id => $items )
if ( isset($terms_by_id[$id]) )
$terms_by_id[$id]->count = count($items);
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @param array $terms List of Term taxonomy IDs
- * @param object $taxonomy Current taxonomy object of terms
+ * @param array $terms List of Term taxonomy IDs.
+ * @param object $taxonomy Current taxonomy object of terms.
*/
function _update_post_term_count( $terms, $taxonomy ) {
global $wpdb;
foreach ( (array) $terms as $term ) {
$count = 0;
- // Attachments can be 'inherit' status, we need to base count off the parent's status if so
+ // Attachments can be 'inherit' status, we need to base count off the parent's status if so.
if ( $check_attachments )
$count += (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships, $wpdb->posts p1 WHERE p1.ID = $wpdb->term_relationships.object_id AND ( post_status = 'publish' OR ( post_status = 'inherit' AND post_parent > 0 AND ( SELECT post_status FROM $wpdb->posts WHERE ID = p1.post_parent ) = 'publish' ) ) AND post_type = 'attachment' AND term_taxonomy_id = %d", $term ) );
/**
* Will update term count based on number of objects.
*
- * Default callback for the link_category taxonomy.
+ * Default callback for the 'link_category' taxonomy.
*
* @since 3.3.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @param array $terms List of Term taxonomy IDs
- * @param object $taxonomy Current taxonomy object of terms
+ * @param array $terms List of term taxonomy IDs.
+ * @param object $taxonomy Current taxonomy object of terms.
*/
function _update_generic_term_count( $terms, $taxonomy ) {
global $wpdb;
}
/**
- * Create a new term for a term_taxonomy item that currently shares its term with another term_taxonomy.
+ * Create a new term for a term_taxonomy item that currently shares its term
+ * with another term_taxonomy.
*
* @ignore
* @since 4.2.0
- *
- * @param int $term_id ID of the shared term.
- * @param int $term_taxonomy_id ID of the term_taxonomy item to receive a new term.
+ * @since 4.3.0 Introduced `$record` parameter. Also, `$term_id` and
+ * `$term_taxonomy_id` can now accept objects.
+ *
+ * @global wpdb $wpdb
+ *
+ * @param int|object $term_id ID of the shared term, or the shared term object.
+ * @param int|object $term_taxonomy_id ID of the term_taxonomy item to receive a new term, or the term_taxonomy object
+ * (corresponding to a row from the term_taxonomy table).
+ * @param bool $record Whether to record data about the split term in the options table. The recording
+ * process has the potential to be resource-intensive, so during batch operations
+ * it can be beneficial to skip inline recording and do it just once, after the
+ * batch is processed. Only set this to `false` if you know what you are doing.
+ * Default: true.
* @return int|WP_Error When the current term does not need to be split (or cannot be split on the current
* database schema), `$term_id` is returned. When the term is successfully split, the
* new term_id is returned. A WP_Error is returned for miscellaneous errors.
*/
-function _split_shared_term( $term_id, $term_taxonomy_id ) {
+function _split_shared_term( $term_id, $term_taxonomy_id, $record = true ) {
global $wpdb;
- // Don't try to split terms if database schema does not support shared slugs.
- $current_db_version = get_option( 'db_version' );
- if ( $current_db_version < 30133 ) {
- return $term_id;
+ if ( is_object( $term_id ) ) {
+ $shared_term = $term_id;
+ $term_id = intval( $shared_term->term_id );
+ }
+
+ if ( is_object( $term_taxonomy_id ) ) {
+ $term_taxonomy = $term_taxonomy_id;
+ $term_taxonomy_id = intval( $term_taxonomy->term_taxonomy_id );
}
// If there are no shared term_taxonomy rows, there's nothing to do here.
$shared_tt_count = $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_taxonomy tt WHERE tt.term_id = %d AND tt.term_taxonomy_id != %d", $term_id, $term_taxonomy_id ) );
+
if ( ! $shared_tt_count ) {
return $term_id;
}
+ /*
+ * Verify that the term_taxonomy_id passed to the function is actually associated with the term_id.
+ * If there's a mismatch, it may mean that the term is already split. Return the actual term_id from the db.
+ */
+ $check_term_id = $wpdb->get_var( $wpdb->prepare( "SELECT term_id FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) );
+ if ( $check_term_id != $term_id ) {
+ return $check_term_id;
+ }
+
// Pull up data about the currently shared slug, which we'll use to populate the new one.
- $shared_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.* FROM $wpdb->terms t WHERE t.term_id = %d", $term_id ) );
+ if ( empty( $shared_term ) ) {
+ $shared_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.* FROM $wpdb->terms t WHERE t.term_id = %d", $term_id ) );
+ }
$new_term_data = array(
'name' => $shared_term->name,
);
// Reassign child terms to the new parent.
- $term_taxonomy = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) );
- $children_tt_ids = $wpdb->get_col( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_taxonomy WHERE taxonomy = %s AND parent = %d", $term_taxonomy->taxonomy, $term_id ) );
+ if ( empty( $term_taxonomy ) ) {
+ $term_taxonomy = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) );
+ }
+ $children_tt_ids = $wpdb->get_col( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_taxonomy WHERE parent = %d AND taxonomy = %s", $term_id, $term_taxonomy->taxonomy ) );
if ( ! empty( $children_tt_ids ) ) {
foreach ( $children_tt_ids as $child_tt_id ) {
$wpdb->update( $wpdb->term_taxonomy,
}
// Keep a record of term_ids that have been split, keyed by old term_id. See {@see wp_get_split_term()}.
- $split_term_data = get_option( '_split_terms', array() );
- if ( ! isset( $split_term_data[ $term_id ] ) ) {
- $split_term_data[ $term_id ] = array();
- }
-
- $split_term_data[ $term_id ][ $term_taxonomy->taxonomy ] = $new_term_id;
+ if ( $record ) {
+ $split_term_data = get_option( '_split_terms', array() );
+ if ( ! isset( $split_term_data[ $term_id ] ) ) {
+ $split_term_data[ $term_id ] = array();
+ }
- update_option( '_split_terms', $split_term_data );
+ $split_term_data[ $term_id ][ $term_taxonomy->taxonomy ] = $new_term_id;
+ update_option( '_split_terms', $split_term_data );
+ }
/**
* Fires after a previously shared taxonomy term is split into two separate terms.
return $new_term_id;
}
+/**
+ * Splits a batch of shared taxonomy terms.
+ *
+ * @since 4.3.0
+ *
+ * @global wpdb $wpdb WordPress database abstraction object.
+ */
+function _wp_batch_split_terms() {
+ global $wpdb;
+
+ $lock_name = 'term_split.lock';
+
+ // Try to lock.
+ $lock_result = $wpdb->query( $wpdb->prepare( "INSERT IGNORE INTO `$wpdb->options` ( `option_name`, `option_value`, `autoload` ) VALUES (%s, %s, 'no') /* LOCK */", $lock_name, time() ) );
+
+ if ( ! $lock_result ) {
+ $lock_result = get_option( $lock_name );
+
+ // Bail if we were unable to create a lock, or if the existing lock is still valid.
+ if ( ! $lock_result || ( $lock_result > ( time() - HOUR_IN_SECONDS ) ) ) {
+ wp_schedule_single_event( time() + ( 5 * MINUTE_IN_SECONDS ), 'wp_split_shared_term_batch' );
+ return;
+ }
+ }
+
+ // Update the lock, as by this point we've definitely got a lock, just need to fire the actions.
+ update_option( $lock_name, time() );
+
+ // Get a list of shared terms (those with more than one associated row in term_taxonomy).
+ $shared_terms = $wpdb->get_results(
+ "SELECT tt.term_id, t.*, count(*) as term_tt_count FROM {$wpdb->term_taxonomy} tt
+ LEFT JOIN {$wpdb->terms} t ON t.term_id = tt.term_id
+ GROUP BY t.term_id
+ HAVING term_tt_count > 1
+ LIMIT 10"
+ );
+
+ // No more terms, we're done here.
+ if ( ! $shared_terms ) {
+ update_option( 'finished_splitting_shared_terms', true );
+ delete_option( $lock_name );
+ return;
+ }
+
+ // Shared terms found? We'll need to run this script again.
+ wp_schedule_single_event( time() + ( 2 * MINUTE_IN_SECONDS ), 'wp_split_shared_term_batch' );
+
+ // Rekey shared term array for faster lookups.
+ $_shared_terms = array();
+ foreach ( $shared_terms as $shared_term ) {
+ $term_id = intval( $shared_term->term_id );
+ $_shared_terms[ $term_id ] = $shared_term;
+ }
+ $shared_terms = $_shared_terms;
+
+ // Get term taxonomy data for all shared terms.
+ $shared_term_ids = implode( ',', array_keys( $shared_terms ) );
+ $shared_tts = $wpdb->get_results( "SELECT * FROM {$wpdb->term_taxonomy} WHERE `term_id` IN ({$shared_term_ids})" );
+
+ // Split term data recording is slow, so we do it just once, outside the loop.
+ $split_term_data = get_option( '_split_terms', array() );
+ $skipped_first_term = $taxonomies = array();
+ foreach ( $shared_tts as $shared_tt ) {
+ $term_id = intval( $shared_tt->term_id );
+
+ // Don't split the first tt belonging to a given term_id.
+ if ( ! isset( $skipped_first_term[ $term_id ] ) ) {
+ $skipped_first_term[ $term_id ] = 1;
+ continue;
+ }
+
+ if ( ! isset( $split_term_data[ $term_id ] ) ) {
+ $split_term_data[ $term_id ] = array();
+ }
+
+ // Keep track of taxonomies whose hierarchies need flushing.
+ if ( ! isset( $taxonomies[ $shared_tt->taxonomy ] ) ) {
+ $taxonomies[ $shared_tt->taxonomy ] = 1;
+ }
+
+ // Split the term.
+ $split_term_data[ $term_id ][ $shared_tt->taxonomy ] = _split_shared_term( $shared_terms[ $term_id ], $shared_tt, false );
+ }
+
+ // Rebuild the cached hierarchy for each affected taxonomy.
+ foreach ( array_keys( $taxonomies ) as $tax ) {
+ delete_option( "{$tax}_children" );
+ _get_term_hierarchy( $tax );
+ }
+
+ update_option( '_split_terms', $split_term_data );
+
+ delete_option( $lock_name );
+}
+
+/**
+ * In order to avoid the _wp_batch_split_terms() job being accidentally removed,
+ * check that it's still scheduled while we haven't finished splitting terms.
+ *
+ * @ignore
+ * @since 4.3.0
+ */
+function _wp_check_for_scheduled_split_terms() {
+ if ( ! get_option( 'finished_splitting_shared_terms' ) && ! wp_next_scheduled( 'wp_split_shared_term_batch' ) ) {
+ wp_schedule_single_event( time() + MINUTE_IN_SECONDS, 'wp_split_shared_term_batch' );
+ }
+}
+
/**
* Check default categories when a term gets split to see if any of them need to be updated.
*
* @ignore
* @since 4.2.0
*
+ * @global wpdb $wpdb
+ *
* @param int $term_id ID of the formerly shared term.
* @param int $new_term_id ID of the new term created for the $term_taxonomy_id.
* @param int $term_taxonomy_id ID for the term_taxonomy row affected by the split.
}
}
+/**
+ * If the term being split is a nav_menu, change associations.
+ *
+ * @ignore
+ * @since 4.3.0
+ *
+ * @global wpdb $wpdb
+ *
+ * @param int $term_id ID of the formerly shared term.
+ * @param int $new_term_id ID of the new term created for the $term_taxonomy_id.
+ * @param int $term_taxonomy_id ID for the term_taxonomy row affected by the split.
+ * @param string $taxonomy Taxonomy for the split term.
+ */
+function _wp_check_split_nav_menu_terms( $term_id, $new_term_id, $term_taxonomy_id, $taxonomy ) {
+ if ( 'nav_menu' !== $taxonomy ) {
+ return;
+ }
+
+ // Update menu locations.
+ $locations = get_nav_menu_locations();
+ foreach ( $locations as $location => $menu_id ) {
+ if ( $term_id == $menu_id ) {
+ $locations[ $location ] = $new_term_id;
+ }
+ }
+ set_theme_mod( 'nav_menu_locations', $locations );
+}
+
/**
* Get data about terms that previously shared a single term_id, but have since been split.
*
*
* @param int $old_term_id Term ID. This is the old, pre-split term ID.
* @param string $taxonomy Taxonomy that the term belongs to.
- * @return bool|int If a previously split term is found corresponding to the old term_id and taxonomy,
- * the new term_id will be returned. If no previously split term is found matching
- * the parameters, returns false.
+ * @return int|false If a previously split term is found corresponding to the old term_id and taxonomy,
+ * the new term_id will be returned. If no previously split term is found matching
+ * the parameters, returns false.
*/
function wp_get_split_term( $old_term_id, $taxonomy ) {
$split_terms = wp_get_split_terms( $old_term_id );
*
* @since 2.5.0
*
+ * @global WP_Rewrite $wp_rewrite
+ *
* @param object|int|string $term The term object, ID, or slug whose link will be retrieved.
* @param string $taxonomy Optional. Taxonomy. Default empty.
* @return string|WP_Error HTML link to taxonomy term archive on success, WP_Error if term does not exist.
*/
-function get_term_link( $term, $taxonomy = '') {
+function get_term_link( $term, $taxonomy = '' ) {
global $wp_rewrite;
if ( !is_object($term) ) {
- if ( is_int($term) ) {
- $term = get_term($term, $taxonomy);
+ if ( is_int( $term ) ) {
+ $term = get_term( $term, $taxonomy );
} else {
- $term = get_term_by('slug', $term, $taxonomy);
+ $term = get_term_by( 'slug', $term, $taxonomy );
}
}
* @since 2.5.0
*
* @param array $args {
- * Arguments about which post to use and how to format the output. Shares all of the arguments supported by
- * {@link get_the_taxonomies()}, in addition to the following.
+ * Arguments about which post to use and how to format the output. Shares all of the arguments
+ * supported by get_the_taxonomies(), in addition to the following.
*
* @type int|WP_Post $post Post ID or object to get taxonomies of. Default current post.
* @type string $before Displays before the taxonomies. Default empty string.
*
* @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
* @param array $args {
- * Arguments about how to format the list of taxonomies.
+ * Optional. Arguments about how to format the list of taxonomies. Default empty array.
*
* @type string $template Template for displaying a taxonomy label and list of terms.
* Default is "Label: Terms."
*
* @since 2.7.0
*
- * @param int $object_id ID of the object (post ID, link ID, ...)
- * @param string $taxonomy Single taxonomy name
- * @param int|string|array $terms Optional. Term term_id, name, slug or array of said
+ * @param int $object_id ID of the object (post ID, link ID, ...).
+ * @param string $taxonomy Single taxonomy name.
+ * @param int|string|array $terms Optional. Term term_id, name, slug or array of said. Default null.
* @return bool|WP_Error WP_Error on input error.
*/
function is_object_in_term( $object_id, $taxonomy, $terms = null ) {
*
* @since 3.0.0
*
- * @param string $object_type Object type string
- * @param string $taxonomy Single taxonomy name
+ * @param string $object_type Object type string.
+ * @param string $taxonomy Single taxonomy name.
* @return bool True if object is associated with the taxonomy, otherwise false.
*/
-function is_object_in_taxonomy($object_type, $taxonomy) {
- $taxonomies = get_object_taxonomies($object_type);
-
- if ( empty($taxonomies) )
+function is_object_in_taxonomy( $object_type, $taxonomy ) {
+ $taxonomies = get_object_taxonomies( $object_type );
+ if ( empty( $taxonomies ) ) {
return false;
-
- if ( in_array($taxonomy, $taxonomies) )
- return true;
-
- return false;
+ }
+ return in_array( $taxonomy, $taxonomies );
}
/**
* Filter a given object's ancestors.
*
* @since 3.1.0
- * @since 4.1.0 Introduced the `$resource_type` parameter.
+ * @since 4.1.1 Introduced the `$resource_type` parameter.
*
* @param array $ancestors An array of object ancestors.
* @param int $object_id Object ID.
}
/**
- * Returns the term's parent's term_ID
+ * Returns the term's parent's term_ID.
*
* @since 3.1.0
*
- * @param int $term_id
- * @param string $taxonomy
- *
- * @return int|bool false on error
+ * @param int $term_id Term ID.
+ * @param string $taxonomy Taxonomy name.
+ * @return int|false False on error.
*/
function wp_get_term_taxonomy_parent_id( $term_id, $taxonomy ) {
$term = get_term( $term_id, $taxonomy );
- if ( !$term || is_wp_error( $term ) )
+ if ( ! $term || is_wp_error( $term ) ) {
return false;
+ }
return (int) $term->parent;
}
* Checks the given subset of the term hierarchy for hierarchy loops.
* Prevents loops from forming and breaks those that it finds.
*
- * Attached to the wp_update_term_parent filter.
+ * Attached to the {@see 'wp_update_term_parent'} filter.
*
* @since 3.1.0
*
- * @param int $parent term_id of the parent for the term we're checking.
- * @param int $term_id The term we're checking.
+ * @param int $parent `term_id` of the parent for the term we're checking.
+ * @param int $term_id The term we're checking.
* @param string $taxonomy The taxonomy of the term we're checking.
*
* @return int The new parent for the term.
if ( !$parent )
return 0;
- // Can't be its own parent
+ // Can't be its own parent.
if ( $parent == $term_id )
return 0;
- // Now look for larger loops
-
+ // Now look for larger loops.
if ( !$loop = wp_find_hierarchy_loop( 'wp_get_term_taxonomy_parent_id', $term_id, $parent, array( $taxonomy ) ) )
return $parent; // No loop
- // Setting $parent to the given value causes a loop
+ // Setting $parent to the given value causes a loop.
if ( isset( $loop[$term_id] ) )
return 0;