diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index bba09b4fd2..ffb18e1abc 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -209,8 +209,8 @@ function get_object_taxonomies( $object, $output = 'names' ) { * * @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|bool The Taxonomy Object or false if $taxonomy doesn't exist. */ function get_taxonomy( $taxonomy ) { global $wp_taxonomies; @@ -230,7 +230,7 @@ function get_taxonomy( $taxonomy ) { * * @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 ) { @@ -249,8 +249,8 @@ 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) ) @@ -319,6 +319,8 @@ function is_taxonomy_hierarchical($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. * @@ -473,10 +475,12 @@ function register_taxonomy( $taxonomy, $object_type, $args = array() ) { * * 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 + * @param object $tax Taxonomy object. + * @return object object with all the labels as member variables. */ function get_taxonomy_labels( $tax ) { @@ -518,9 +522,9 @@ function get_taxonomy_labels( $tax ) { * * @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 + * @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; @@ -588,10 +592,10 @@ function unregister_taxonomy_for_object_type( $taxonomy, $object_type ) { * * @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() ) { @@ -647,7 +651,7 @@ function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) { /** * 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. * @@ -697,7 +701,7 @@ class WP_Tax_Query { * 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 @@ -896,7 +900,7 @@ class WP_Tax_Query { /** * 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 @@ -1017,7 +1021,7 @@ class WP_Tax_Query { * * @global wpdb $wpdb The WordPress database abstraction object. * - * @param array $clause Query clause, passed by reference + * @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. @@ -1135,7 +1139,7 @@ class WP_Tax_Query { * 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 @@ -1229,7 +1233,7 @@ class WP_Tax_Query { * * @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; @@ -1308,15 +1312,17 @@ class WP_Tax_Query { * 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. @@ -1407,6 +1413,8 @@ function get_term($term, $taxonomy, $output = OBJECT, $filter = 'raw') { * 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. @@ -1479,9 +1487,9 @@ function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw * * @since 2.3.0 * - * @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) ) @@ -1517,10 +1525,10 @@ function get_term_children( $term_id, $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. + * @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. */ function get_term_field( $field, $term, $taxonomy, $context = 'display' ) { @@ -1546,8 +1554,8 @@ function get_term_field( $field, $term, $taxonomy, $context = 'display' ) { * * @since 2.3.0 * - * @param int|object $id Term ID or Object - * @param string $taxonomy Taxonomy Name + * @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. */ function get_term_to_edit( $id, $taxonomy ) { @@ -1568,15 +1576,15 @@ function get_term_to_edit( $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 @@ -1692,7 +1700,7 @@ function get_terms( $taxonomies, $args = '' ) { * * @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 ); @@ -1724,7 +1732,7 @@ function get_terms( $taxonomies, $args = '' ) { } } - // $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' ); @@ -1743,7 +1751,7 @@ function get_terms( $taxonomies, $args = '' ) { * * @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; @@ -1770,12 +1778,13 @@ function get_terms( $taxonomies, $args = '' ) { } 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. */ @@ -1847,7 +1856,7 @@ function get_terms( $taxonomies, $args = '' ) { * * @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. */ @@ -1900,7 +1909,7 @@ function get_terms( $taxonomies, $args = '' ) { $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; @@ -1975,6 +1984,7 @@ function get_terms( $taxonomies, $args = '' ) { * @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' ] : ''; @@ -2032,7 +2042,7 @@ function get_terms( $taxonomies, $args = '' ) { } } - // It really is empty + // It really is empty. unset($terms[$k]); } } @@ -2149,10 +2159,10 @@ function term_exists( $term, $taxonomy = '', $parent = null ) { * * @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 ) ) @@ -2179,10 +2189,11 @@ function term_is_ancestor_of( $term1, $term2, $taxonomy ) { * * @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') { @@ -2227,12 +2238,13 @@ function sanitize_term($term, $taxonomy, $context = 'display') { * * @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' ); @@ -2272,6 +2284,7 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) { * @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 @@ -2301,6 +2314,7 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) { * @param mixed $value Value of the taxonomy field. */ $value = apply_filters( "pre_{$taxonomy}_{$field}", $value ); + // Back compat filters if ( 'slug' == $field ) { /** @@ -2332,7 +2346,7 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) { /** * 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 @@ -2360,7 +2374,7 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) { /** * 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 @@ -2385,6 +2399,8 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) { * * 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 @@ -2415,7 +2431,7 @@ function wp_count_terms( $taxonomy, $args = array() ) { * * @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 ) { @@ -2437,19 +2453,21 @@ 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. + * @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. */ function wp_delete_term( $term, $taxonomy, $args = array() ) { @@ -2513,6 +2531,7 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) { * @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. @@ -2544,7 +2563,7 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) { 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 ); @@ -2601,7 +2620,7 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) { * @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 ); @@ -3198,9 +3217,9 @@ function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) { * * @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 ) { @@ -3214,9 +3233,9 @@ 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 ) { @@ -3276,6 +3295,7 @@ 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; @@ -3287,7 +3307,7 @@ function wp_remove_object_terms( $object_id, $terms, $taxonomy ) { /** * 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. * @@ -3297,17 +3317,17 @@ function wp_remove_object_terms( $object_id, $terms, $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 too. * @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 ) ) @@ -3318,8 +3338,10 @@ function wp_unique_term_slug($slug, $term) { return $slug; } - // If the taxonomy supports hierarchy and the term has a parent, make the slug unique - // by incorporating parent slugs. + /* + * 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) ) { $the_parent = $term->parent; while ( ! empty($the_parent) ) { @@ -3373,16 +3395,16 @@ function wp_unique_term_slug($slug, $term) { * 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() ) { @@ -3529,6 +3551,7 @@ 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 ) ); /** @@ -3541,7 +3564,7 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) { */ 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 ) { @@ -3638,8 +3661,8 @@ function wp_defer_term_counting($defer=null) { * * @global wpdb $wpdb WordPress database abstraction object. * - * @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 ) { @@ -3673,7 +3696,7 @@ 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. */ @@ -3711,16 +3734,16 @@ function wp_update_term_count_now( $terms, $taxonomy ) { /** * 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) ) @@ -3752,9 +3775,11 @@ function clean_object_term_cache($object_ids, $object_type) { * * @global wpdb $wpdb WordPress database abstraction object. * - * @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; @@ -3812,11 +3837,12 @@ function clean_term_cache($ids, $taxonomy = '', $clean_taxonomy = true) { * * @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|array 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) { +function get_object_term_cache( $id, $taxonomy ) { $cache = wp_cache_get($id, "{$taxonomy}_relationships"); return $cache; } @@ -3833,7 +3859,7 @@ function get_object_term_cache($id, $taxonomy) { * * @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. @@ -3890,10 +3916,10 @@ function update_object_term_cache($object_ids, $object_type) { * * @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) ) @@ -3910,13 +3936,13 @@ function update_term_cache($terms, $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"); @@ -3937,19 +3963,20 @@ function _get_term_hierarchy($taxonomy) { /** * 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. For performance, term_ids are used as array keys, with 1 as value. + * @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 The subset of $terms that are descendants of $term_id. */ function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array() ) { @@ -4012,11 +4039,11 @@ function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array() * * @global wpdb $wpdb WordPress database abstraction object. * - * @param array $terms List of Term IDs - * @param string $taxonomy Term Context + * @param array $terms List of term IDs, passed by reference. + * @param string $taxonomy Term context. * @return null Will break from function if conditions are not met. */ -function _pad_term_counts(&$terms, $taxonomy) { +function _pad_term_counts( &$terms, $taxonomy ) { global $wpdb; // This function only works for hierarchical taxonomies like post categories. @@ -4037,7 +4064,7 @@ function _pad_term_counts(&$terms, $taxonomy) { $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'"); @@ -4046,7 +4073,7 @@ function _pad_term_counts(&$terms, $taxonomy) { $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(); @@ -4064,7 +4091,7 @@ function _pad_term_counts(&$terms, $taxonomy) { } } - // 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); @@ -4085,8 +4112,8 @@ function _pad_term_counts(&$terms, $taxonomy) { * * @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; @@ -4109,7 +4136,7 @@ function _update_post_term_count( $terms, $taxonomy ) { 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 ) ); @@ -4128,14 +4155,14 @@ function _update_post_term_count( $terms, $taxonomy ) { /** * 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; @@ -4355,7 +4382,7 @@ function wp_get_split_term( $old_term_id, $taxonomy ) { * @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) ) { @@ -4452,8 +4479,8 @@ function get_term_link( $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. @@ -4485,7 +4512,7 @@ function the_taxonomies( $args = array() ) { * * @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." @@ -4563,9 +4590,9 @@ function get_post_taxonomies( $post = 0 ) { * * @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 ) { @@ -4616,8 +4643,8 @@ 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) { @@ -4689,14 +4716,13 @@ function get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' ) } /** - * 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|bool False on error. */ function wp_get_term_taxonomy_parent_id( $term_id, $taxonomy ) { $term = get_term( $term_id, $taxonomy ); @@ -4709,12 +4735,12 @@ function wp_get_term_taxonomy_parent_id( $term_id, $taxonomy ) { * 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. @@ -4724,16 +4750,15 @@ function wp_check_term_hierarchy_for_loops( $parent, $term_id, $taxonomy ) { 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; diff --git a/wp-includes/version.php b/wp-includes/version.php index 8bf557aa28..d3dcc7762b 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '4.3-alpha-32452'; +$wp_version = '4.3-alpha-32453'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.