2007-09-15 13:35:32 -04:00
< ? php
2007-10-15 18:49:31 -04:00
/**
2008-08-30 17:23:43 -04:00
* Taxonomy API
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-15 18:49:31 -04:00
*/
2007-09-15 13:35:32 -04:00
//
// Taxonomy Registration
//
/**
2007-10-21 13:18:24 -04:00
* Default Taxonomy Objects
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ global array $wp_taxonomies
2007-09-15 13:35:32 -04:00
*/
$wp_taxonomies = array ();
2008-12-18 14:12:26 -05:00
$wp_taxonomies [ 'category' ] = ( object ) array ( 'name' => 'category' , 'object_type' => 'post' , 'hierarchical' => true , 'update_count_callback' => '_update_post_term_count' , 'label' => __ ( 'Categories' ));
$wp_taxonomies [ 'post_tag' ] = ( object ) array ( 'name' => 'post_tag' , 'object_type' => 'post' , 'hierarchical' => false , 'update_count_callback' => '_update_post_term_count' , 'label' => __ ( 'Post Tags' ));
2007-09-15 13:35:32 -04:00
$wp_taxonomies [ 'link_category' ] = ( object ) array ( 'name' => 'link_category' , 'object_type' => 'link' , 'hierarchical' => false );
/**
2008-06-22 16:23:23 -04:00
* Return all of the taxonomy names that are of $object_type .
2007-09-15 13:35:32 -04:00
*
* It appears that this function can be used to find all of the names inside of
* $wp_taxonomies global variable .
*
2008-06-22 16:23:23 -04:00
* < code >< ? php $taxonomies = get_object_taxonomies ( 'post' ); ?> </code> Should
* result in < code > Array ( 'category' , 'post_tag' ) </ code >
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2008-02-05 01:47:27 -05:00
*
2007-10-21 13:18:24 -04:00
* @ uses $wp_taxonomies
2007-09-15 13:35:32 -04:00
*
2008-03-26 02:37:19 -04:00
* @ param array | string | object $object Name of the type of taxonomy object , or an object ( row from posts )
2007-10-21 13:18:24 -04:00
* @ return array The names of all taxonomy of $object_type .
2007-09-15 13:35:32 -04:00
*/
2008-03-26 02:37:19 -04:00
function get_object_taxonomies ( $object ) {
2007-09-15 13:35:32 -04:00
global $wp_taxonomies ;
2008-03-26 02:37:19 -04:00
if ( is_object ( $object ) ) {
if ( $object -> post_type == 'attachment' )
return get_attachment_taxonomies ( $object );
$object = $object -> post_type ;
}
$object = ( array ) $object ;
2007-09-15 13:35:32 -04:00
$taxonomies = array ();
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $wp_taxonomies as $taxonomy ) {
2008-03-26 02:37:19 -04:00
if ( array_intersect ( $object , ( array ) $taxonomy -> object_type ) )
2007-09-15 13:35:32 -04:00
$taxonomies [] = $taxonomy -> name ;
}
return $taxonomies ;
}
/**
2008-06-22 16:23:23 -04:00
* Retrieves the taxonomy object of $taxonomy .
2007-09-15 13:35:32 -04:00
*
* The get_taxonomy function will first check that the parameter string given
* is a taxonomy object and if it is , it will return it .
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses $wp_taxonomies
* @ uses is_taxonomy () Checks whether taxonomy exists
2007-09-15 13:35:32 -04:00
*
2007-10-21 13:18:24 -04:00
* @ param string $taxonomy Name of taxonomy object to return
* @ return object | bool The Taxonomy Object or false if $taxonomy doesn ' t exist
2007-09-15 13:35:32 -04:00
*/
function get_taxonomy ( $taxonomy ) {
global $wp_taxonomies ;
if ( ! is_taxonomy ( $taxonomy ) )
return false ;
return $wp_taxonomies [ $taxonomy ];
}
/**
2008-06-22 16:23:23 -04:00
* Checks that the taxonomy name exists .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2008-02-05 01:47:27 -05:00
*
2007-10-21 13:18:24 -04:00
* @ uses $wp_taxonomies
*
2007-09-15 13:35:32 -04:00
* @ param string $taxonomy Name of taxonomy object
* @ return bool Whether the taxonomy exists or not .
*/
function is_taxonomy ( $taxonomy ) {
global $wp_taxonomies ;
return isset ( $wp_taxonomies [ $taxonomy ]);
}
/**
2008-06-22 16:23:23 -04:00
* Whether the taxonomy object is hierarchical .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* Checks to make sure that the taxonomy is an object first . Then Gets the
* object , and finally returns the hierarchical value in the object .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* A false return value might also mean that the taxonomy does not exist .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses is_taxonomy () Checks whether taxonomy exists
* @ uses get_taxonomy () Used to get the taxonomy object
*
2007-09-15 13:35:32 -04:00
* @ param string $taxonomy Name of taxonomy object
* @ return bool Whether the taxonomy is hierarchical
*/
function is_taxonomy_hierarchical ( $taxonomy ) {
if ( ! is_taxonomy ( $taxonomy ) )
return false ;
$taxonomy = get_taxonomy ( $taxonomy );
return $taxonomy -> hierarchical ;
}
/**
2008-06-22 16:23:23 -04:00
* Create or modify a taxonomy object . Do not use before init .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* A simple function for creating or modifying a taxonomy object based on the
* parameters given . The function will accept an array ( third optional
* parameter ), along with strings for the taxonomy name and another string for
* the object type .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* Nothing is returned , so expect error maybe or use is_taxonomy () to check
* whether taxonomy exists .
2007-09-15 13:35:32 -04:00
*
2007-10-21 13:18:24 -04:00
* Optional $args contents :
2008-06-22 16:23:23 -04:00
*
* hierarachical - has some defined purpose at other parts of the API and is a
* boolean value .
*
* update_count_callback - works much like a hook , in that it will be called
* when the count is updated .
*
* rewrite - false to prevent rewrite , or array ( 'slug' => $slug ) to customize
* permastruct ; default will use $taxonomy as slug .
*
* query_var - false to prevent queries , or string to customize query var
* ( ? $query_var = $term ); default will use $taxonomy as query var .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wp_taxonomies Inserts new taxonomy object into the list
2008-03-26 02:37:19 -04:00
* @ uses $wp_rewrite Adds rewrite tags and permastructs
* @ uses $wp Adds query vars
2008-02-05 01:47:27 -05:00
*
2007-09-15 13:35:32 -04:00
* @ param string $taxonomy Name of taxonomy object
2008-03-24 18:43:20 -04:00
* @ param array | string $object_type Name of the object type for the taxonomy object .
2007-09-15 13:35:32 -04:00
* @ param array | string $args See above description for the two keys values .
*/
function register_taxonomy ( $taxonomy , $object_type , $args = array () ) {
2008-03-26 02:37:19 -04:00
global $wp_taxonomies , $wp_rewrite , $wp ;
2007-09-15 13:35:32 -04:00
2008-03-26 02:37:19 -04:00
$defaults = array ( 'hierarchical' => false , 'update_count_callback' => '' , 'rewrite' => true , 'query_var' => true );
2007-09-15 13:35:32 -04:00
$args = wp_parse_args ( $args , $defaults );
2008-03-27 02:30:20 -04:00
if ( false !== $args [ 'query_var' ] && ! empty ( $wp ) ) {
2008-05-15 22:35:24 -04:00
if ( true === $args [ 'query_var' ] )
2008-03-26 02:37:19 -04:00
$args [ 'query_var' ] = $taxonomy ;
$args [ 'query_var' ] = sanitize_title_with_dashes ( $args [ 'query_var' ]);
$wp -> add_query_var ( $args [ 'query_var' ]);
}
2008-03-27 02:30:20 -04:00
if ( false !== $args [ 'rewrite' ] && ! empty ( $wp_rewrite ) ) {
2008-03-23 13:02:11 -04:00
if ( ! is_array ( $args [ 'rewrite' ]) )
$args [ 'rewrite' ] = array ();
if ( ! isset ( $args [ 'rewrite' ][ 'slug' ]) )
$args [ 'rewrite' ][ 'slug' ] = sanitize_title_with_dashes ( $taxonomy );
2008-03-26 02:37:19 -04:00
$wp_rewrite -> add_rewrite_tag ( " % $taxonomy % " , '([^/]+)' , $args [ 'query_var' ] ? " { $args [ 'query_var' ] } = " : " taxonomy= $taxonomy &term= $term " );
$wp_rewrite -> add_permastruct ( $taxonomy , " { $args [ 'rewrite' ][ 'slug' ] } /% $taxonomy % " );
2008-03-23 13:02:11 -04:00
}
2007-09-15 13:35:32 -04:00
$args [ 'name' ] = $taxonomy ;
$args [ 'object_type' ] = $object_type ;
$wp_taxonomies [ $taxonomy ] = ( object ) $args ;
}
//
// Term API
//
/**
2008-06-22 16:23:23 -04:00
* Retrieve object_ids of valid taxonomy and term .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* The strings of $taxonomies must exist before this function will continue . On
* failure of finding a valid taxonomy , it will return an WP_Error class , kind
* of like Exceptions in PHP 5 , except you can ' t catch them . Even so , you can
* still test for the WP_Error class and get the error message .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* The $terms aren ' t checked the same as $taxonomies , but still need to exist
* for $object_ids to be returned .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* It is possible to change the order that object_ids is returned by either
* using PHP sort family functions or using the database by using $args with
* either ASC or DESC array . The value should be in the key named 'order' .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses $wpdb
* @ uses wp_parse_args () Creates an array from string $args .
2007-10-15 18:49:31 -04:00
*
2007-09-15 13:35:32 -04:00
* @ param string | array $terms String of term or array of string values 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
2007-10-21 13:18:24 -04:00
* @ 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 .
2007-09-15 13:35:32 -04:00
*/
function get_objects_in_term ( $terms , $taxonomies , $args = array () ) {
global $wpdb ;
if ( ! is_array ( $terms ) )
$terms = array ( $terms );
if ( ! is_array ( $taxonomies ) )
$taxonomies = array ( $taxonomies );
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $taxonomies as $taxonomy ) {
2007-09-15 13:35:32 -04:00
if ( ! is_taxonomy ( $taxonomy ) )
return new WP_Error ( 'invalid_taxonomy' , __ ( 'Invalid Taxonomy' ));
}
$defaults = array ( 'order' => 'ASC' );
$args = wp_parse_args ( $args , $defaults );
extract ( $args , EXTR_SKIP );
2007-10-12 23:51:11 -04:00
$order = ( 'desc' == strtolower ( $order ) ) ? 'DESC' : 'ASC' ;
2007-09-15 13:35:32 -04:00
$terms = array_map ( 'intval' , $terms );
$taxonomies = " ' " . implode ( " ', ' " , $taxonomies ) . " ' " ;
$terms = " ' " . implode ( " ', ' " , $terms ) . " ' " ;
$object_ids = $wpdb -> get_col ( " SELECT tr.object_id FROM $wpdb->term_relationships AS tr INNER JOIN $wpdb->term_taxonomy AS tt ON tr.term_taxonomy_id = tt.term_taxonomy_id WHERE tt.taxonomy IN ( $taxonomies ) AND tt.term_id IN ( $terms ) ORDER BY tr.object_id $order " );
if ( ! $object_ids )
return array ();
return $object_ids ;
}
/**
2008-06-22 16:23:23 -04:00
* Get all Term data from database by Term ID .
2007-10-15 18:49:31 -04:00
*
2008-06-22 16:23:23 -04:00
* The usage of the get_term function is to apply filters to a term object . It
* is possible to get a term object from the database before applying the
2007-10-21 13:18:24 -04:00
* filters .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* $term ID must be part of $taxonomy , to get from the database . Failure , might
* be able to be captured by the hooks . Failure would be the same value as $wpdb
* returns for the get_row method .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* There are two hooks , one is specifically for each term , named 'get_term' , and
* the second is for the taxonomy name , 'term_$taxonomy' . Both hooks gets the
* term object , and the taxonomy name as parameters . Both hooks are expected to
* return a Term object .
2007-10-21 13:18:24 -04:00
*
2008-06-22 16:23:23 -04:00
* '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 .
2007-10-21 13:18:24 -04:00
*
2008-06-22 16:23:23 -04:00
* '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 .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses $wpdb
2007-12-13 19:25:39 -05:00
* @ uses sanitize_term () Cleanses the term based on $filter context before returning .
* @ see sanitize_term_field () The $context param lists the available values for get_term_by () $filter param .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ 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
2007-12-13 19:25:39 -05:00
* @ param string $filter Optional , default is raw or no WordPress defined filter will applied .
2007-10-21 13:18:24 -04:00
* @ return mixed | 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 .
2007-09-15 13:35:32 -04:00
*/
function & get_term ( $term , $taxonomy , $output = OBJECT , $filter = 'raw' ) {
global $wpdb ;
2008-08-14 13:00:37 -04:00
if ( empty ( $term ) ) {
$error = new WP_Error ( 'invalid_term' , __ ( 'Empty Term' ));
return $error ;
}
2007-09-15 13:35:32 -04:00
2008-08-14 13:00:37 -04:00
if ( ! is_taxonomy ( $taxonomy ) ) {
$error = new WP_Error ( 'invalid_taxonomy' , __ ( 'Invalid Taxonomy' ));
return $error ;
}
2007-09-15 13:35:32 -04:00
2008-11-17 15:03:31 -05:00
if ( is_object ( $term ) && empty ( $term -> filter ) ) {
2007-09-15 13:35:32 -04:00
wp_cache_add ( $term -> term_id , $term , $taxonomy );
$_term = $term ;
} else {
2008-11-17 15:03:31 -05:00
if ( is_object ( $term ) )
$term = $term -> term_id ;
2007-09-15 13:35:32 -04:00
$term = ( int ) $term ;
if ( ! $_term = wp_cache_get ( $term , $taxonomy ) ) {
2007-10-12 23:51:11 -04:00
$_term = $wpdb -> get_row ( $wpdb -> prepare ( " SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE tt.taxonomy = %s AND t.term_id = %s LIMIT 1 " , $taxonomy , $term ) );
2007-09-15 13:35:32 -04:00
wp_cache_add ( $term , $_term , $taxonomy );
}
}
2008-02-05 01:47:27 -05:00
2007-09-15 13:35:32 -04:00
$_term = apply_filters ( 'get_term' , $_term , $taxonomy );
$_term = apply_filters ( " get_ $taxonomy " , $_term , $taxonomy );
$_term = sanitize_term ( $_term , $taxonomy , $filter );
if ( $output == OBJECT ) {
return $_term ;
} elseif ( $output == ARRAY_A ) {
2008-11-02 18:52:49 -05:00
$__term = get_object_vars ( $_term );
return $__term ;
2007-09-15 13:35:32 -04:00
} elseif ( $output == ARRAY_N ) {
2008-11-02 18:52:49 -05:00
$__term = array_values ( get_object_vars ( $_term ));
return $__term ;
2007-09-15 13:35:32 -04:00
} else {
return $_term ;
}
}
/**
2008-06-22 16:23:23 -04:00
* Get all Term data from database by Term field and data .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* Warning : $value is not escaped for 'name' $field . You must do it yourself , if
* required .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* The default $field is 'id' , therefore it is possible to also use null for
* field , but not recommended that you do so .
2007-10-15 18:49:31 -04:00
*
2008-06-22 16:23:23 -04:00
* 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 .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses $wpdb
2007-12-13 19:25:39 -05:00
* @ uses sanitize_term () Cleanses the term based on $filter context before returning .
* @ see sanitize_term_field () The $context param lists the available values for get_term_by () $filter param .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ param string $field Either 'slug' , 'name' , or '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
2007-12-13 19:25:39 -05:00
* @ param string $filter Optional , default is raw or no WordPress defined filter will applied .
2007-10-21 13:18:24 -04:00
* @ return mixed Term Row from database . Will return false if $taxonomy does not exist or $term was not found .
2007-09-15 13:35:32 -04:00
*/
function get_term_by ( $field , $value , $taxonomy , $output = OBJECT , $filter = 'raw' ) {
global $wpdb ;
if ( ! is_taxonomy ( $taxonomy ) )
return false ;
if ( 'slug' == $field ) {
$field = 't.slug' ;
$value = sanitize_title ( $value );
if ( empty ( $value ) )
return false ;
} else if ( 'name' == $field ) {
// Assume already escaped
2008-10-17 14:56:56 -04:00
$value = stripslashes ( $value );
2007-09-15 13:35:32 -04:00
$field = 't.name' ;
} else {
$field = 't.term_id' ;
$value = ( int ) $value ;
}
2007-10-12 23:51:11 -04:00
$term = $wpdb -> get_row ( $wpdb -> prepare ( " SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE tt.taxonomy = %s AND $field = %s LIMIT 1 " , $taxonomy , $value ) );
2007-09-15 13:35:32 -04:00
if ( ! $term )
return false ;
wp_cache_add ( $term -> term_id , $term , $taxonomy );
$term = sanitize_term ( $term , $taxonomy , $filter );
if ( $output == OBJECT ) {
return $term ;
} elseif ( $output == ARRAY_A ) {
return get_object_vars ( $term );
} elseif ( $output == ARRAY_N ) {
return array_values ( get_object_vars ( $term ));
} else {
return $term ;
}
}
/**
2008-06-22 16:23:23 -04:00
* Merge all term children into a single array .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* This recursive function will merge all of the children of $term into the same
* array . Only useful for taxonomies which are hierarchical .
2007-09-15 13:35:32 -04:00
*
2007-10-21 13:18:24 -04:00
* Will return an empty array if $term does not exist in $taxonomy .
2008-02-05 01:47:27 -05:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses $wpdb
* @ uses _get_term_hierarchy ()
* @ uses get_term_children () Used to get the children of both $taxonomy and the parent $term
2007-10-15 18:49:31 -04:00
*
2007-09-15 13:35:32 -04:00
* @ param string $term Name of Term to get children
* @ param string $taxonomy Taxonomy Name
2007-10-21 13:18:24 -04:00
* @ return array | WP_Error List of Term Objects . WP_Error returned if $taxonomy does not exist
2007-09-15 13:35:32 -04:00
*/
function get_term_children ( $term , $taxonomy ) {
if ( ! is_taxonomy ( $taxonomy ) )
return new WP_Error ( 'invalid_taxonomy' , __ ( 'Invalid Taxonomy' ));
$terms = _get_term_hierarchy ( $taxonomy );
if ( ! isset ( $terms [ $term ]) )
return array ();
$children = $terms [ $term ];
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $terms [ $term ] as $child ) {
2007-09-15 13:35:32 -04:00
if ( isset ( $terms [ $child ]) )
$children = array_merge ( $children , get_term_children ( $child , $taxonomy ));
}
return $children ;
}
/**
2008-06-22 16:23:23 -04:00
* Get sanitized Term field .
2008-02-05 01:47:27 -05:00
*
2008-06-22 16:23:23 -04:00
* Does checks for $term , based on the $taxonomy . The function is for contextual
* reasons and for simplicity of usage . See sanitize_term_field () for more
* information .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses sanitize_term_field () Passes the return value in sanitize_term_field on success .
2007-10-15 18:49:31 -04:00
*
2007-09-15 13:35:32 -04:00
* @ param string $field Term field to fetch
* @ param int $term Term ID
* @ param string $taxonomy Taxonomy Name
2007-12-13 19:25:39 -05:00
* @ param string $context Optional , default is display . Look at sanitize_term_field () for available options .
2007-10-21 13:18:24 -04:00
* @ return mixed Will return an empty string if $term is not an object or if $field is not set in $term .
2007-09-15 13:35:32 -04:00
*/
function get_term_field ( $field , $term , $taxonomy , $context = 'display' ) {
$term = ( int ) $term ;
$term = get_term ( $term , $taxonomy );
if ( is_wp_error ( $term ) )
return $term ;
if ( ! is_object ( $term ) )
return '' ;
if ( ! isset ( $term -> $field ) )
return '' ;
return sanitize_term_field ( $field , $term -> $field , $term -> term_id , $taxonomy , $context );
}
/**
2008-06-22 16:23:23 -04:00
* Sanitizes Term for editing .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* Return value is sanitize_term () and usage is for sanitizing the term for
* editing . Function is for contextual and simplicity .
2008-02-05 01:47:27 -05:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses sanitize_term () Passes the return value on success
2007-10-15 18:49:31 -04:00
*
2007-09-15 13:35:32 -04:00
* @ param int | object $id Term ID or Object
* @ param string $taxonomy Taxonomy Name
2007-10-21 13:18:24 -04:00
* @ return mixed | null | WP_Error Will return empty string if $term is not an object .
2007-09-15 13:35:32 -04:00
*/
function get_term_to_edit ( $id , $taxonomy ) {
$term = get_term ( $id , $taxonomy );
if ( is_wp_error ( $term ) )
return $term ;
if ( ! is_object ( $term ) )
return '' ;
return sanitize_term ( $term , $taxonomy , 'edit' );
}
/**
2008-11-12 19:20:12 -05:00
* Retrieve the terms in a given taxonomy or list of taxonomies .
2007-10-21 13:18:24 -04:00
*
2008-06-22 16:23:23 -04:00
* You can fully inject any customizations to the query before it is sent , as
* well as control the output with a filter .
2007-10-21 13:18:24 -04:00
*
2008-06-22 16:23:23 -04:00
* The '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 .
2007-10-21 13:18:24 -04:00
*
2008-06-22 16:23:23 -04:00
* The 'list_terms_exclusions' filter passes the compiled exclusions along with
* the $args .
2007-10-21 13:18:24 -04:00
*
2008-11-12 19:20:12 -05:00
* The list of arguments that $args can contain , which will overwrite the defaults :
2008-06-22 16:23:23 -04:00
*
* orderby - Default is 'name' . Can be name , count , or nothing ( will use
* term_id ) .
*
2007-10-21 13:18:24 -04:00
* order - Default is ASC . Can use DESC .
*
2008-11-12 19:20:12 -05:00
* hide_empty - Default is true . Will not return empty terms , which means
* terms whose count is 0 according to the given taxonomy .
2008-12-09 13:03:31 -05:00
*
2008-11-12 19:20:12 -05:00
* exclude - Default is an empty string . A comma - or space - delimited string
2008-12-09 13:03:31 -05:00
* of term ids to exclude from the return array . If 'include' is non - empty ,
2008-11-12 19:20:12 -05:00
* 'exclude' is ignored .
*
2008-12-30 17:30:36 -05:00
* exclude_tree - A comma - or space - delimited string of term ids to exclude
* from the return array , along with all of their descendant terms according to
* the primary taxonomy . If 'include' is non - empty , 'exclude_tree' is ignored .
*
2008-11-12 19:20:12 -05:00
* include - Default is an empty string . A comma - or space - delimited string
* of term ids to include in the return array .
2008-12-09 13:03:31 -05:00
*
2008-11-12 19:20:12 -05:00
* number - The maximum number of terms to return . Default is empty .
2008-12-09 13:03:31 -05:00
*
2008-11-12 19:20:12 -05:00
* offset - The number by which to offset the terms query .
*
2008-12-09 13:03:31 -05:00
* fields - Default is 'all' , which returns an array of term objects .
2008-11-12 19:20:12 -05:00
* If 'fields' is 'ids' or 'names' , returns an array of
* integers or strings , respectively .
*
* slug - Returns terms whose " slug " matches this value . Default is empty string .
2008-12-09 13:03:31 -05:00
*
2008-11-12 19:20:12 -05:00
* hierarchical - Whether to include terms that have non - empty descendants
* ( even if 'hide_empty' is set to true ) .
2008-12-09 13:03:31 -05:00
*
2008-11-12 19:20:12 -05:00
* search - Returned terms ' names will contain the value of ' search ' ,
* case - insensitive . Default is an empty string .
*
* name__like - Returned terms ' names will begin with the value of ' name__like ' ,
* case - insensitive . Default is empty string .
*
* The argument 'pad_counts' , if set to true will include the quantity of a term ' s
* children in the quantity of each term ' s " count " object variable .
*
* The 'get' argument , if set to 'all' instead of its default empty string ,
* returns terms regardless of ancestry or whether the terms are empty .
*
* The 'child_of' argument , when used , should be set to the integer of a term ID . Its default
2008-12-09 13:03:31 -05:00
* is 0. If set to a non - zero value , all returned terms will be descendants
* of that term according to the given taxonomy . Hence 'child_of' is set to 0
* if more than one taxonomy is passed in $taxonomies , because multiple taxonomies
2008-11-12 19:20:12 -05:00
* make term ancestry ambiguous .
*
* The 'parent' argument , when used , should be set to the integer of a term ID . Its default is
* the empty string '' , which has a different meaning from the integer 0.
2008-12-09 13:03:31 -05:00
* If set to an integer value , all returned terms will have as an immediate
2008-11-12 19:20:12 -05:00
* ancestor the term whose ID is specified by that integer according to the given taxonomy .
* The 'parent' argument is different from 'child_of' in that a term X is considered a 'parent'
* of term Y only if term X is the father of term Y , not its grandfather or great - grandfather , etc .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-15 18:49:31 -04:00
*
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
* @ uses wp_parse_args () Merges the defaults with those defined by $args and allows for strings .
2007-09-15 13:35:32 -04:00
*
2007-10-21 13:18:24 -04:00
* @ param string | array Taxonomy name or list of Taxonomy names
* @ param string | array $args The values of what to search for when returning terms
* @ return array | WP_Error List of Term Objects and their children . Will return WP_Error , if any of $taxonomies do not exist .
2007-09-15 13:35:32 -04:00
*/
function & get_terms ( $taxonomies , $args = '' ) {
global $wpdb ;
2008-01-10 15:51:07 -05:00
$empty_array = array ();
2007-09-15 13:35:32 -04:00
$single_taxonomy = false ;
if ( ! is_array ( $taxonomies ) ) {
$single_taxonomy = true ;
$taxonomies = array ( $taxonomies );
}
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $taxonomies as $taxonomy ) {
2007-09-15 13:35:32 -04:00
if ( ! is_taxonomy ( $taxonomy ) )
return new WP_Error ( 'invalid_taxonomy' , __ ( 'Invalid Taxonomy' ));
}
$in_taxonomies = " ' " . implode ( " ', ' " , $taxonomies ) . " ' " ;
$defaults = array ( 'orderby' => 'name' , 'order' => 'ASC' ,
2008-12-30 17:30:36 -05:00
'hide_empty' => true , 'exclude' => '' , 'exclude_tree' => '' , 'include' => '' ,
2007-09-15 13:35:32 -04:00
'number' => '' , 'fields' => 'all' , 'slug' => '' , 'parent' => '' ,
'hierarchical' => true , 'child_of' => 0 , 'get' => '' , 'name__like' => '' ,
2008-02-12 04:02:02 -05:00
'pad_counts' => false , 'offset' => '' , 'search' => '' );
2007-09-15 13:35:32 -04:00
$args = wp_parse_args ( $args , $defaults );
2007-10-12 23:51:11 -04:00
$args [ 'number' ] = absint ( $args [ 'number' ] );
2008-01-25 14:29:01 -05:00
$args [ 'offset' ] = absint ( $args [ 'offset' ] );
2007-09-15 13:35:32 -04:00
if ( ! $single_taxonomy || ! is_taxonomy_hierarchical ( $taxonomies [ 0 ]) ||
'' != $args [ 'parent' ] ) {
$args [ 'child_of' ] = 0 ;
$args [ 'hierarchical' ] = false ;
$args [ 'pad_counts' ] = false ;
}
if ( 'all' == $args [ 'get' ] ) {
$args [ 'child_of' ] = 0 ;
$args [ 'hide_empty' ] = 0 ;
$args [ 'hierarchical' ] = false ;
$args [ 'pad_counts' ] = false ;
}
extract ( $args , EXTR_SKIP );
if ( $child_of ) {
$hierarchy = _get_term_hierarchy ( $taxonomies [ 0 ]);
if ( ! isset ( $hierarchy [ $child_of ]) )
2008-01-10 15:51:07 -05:00
return $empty_array ;
2007-09-15 13:35:32 -04:00
}
if ( $parent ) {
$hierarchy = _get_term_hierarchy ( $taxonomies [ 0 ]);
if ( ! isset ( $hierarchy [ $parent ]) )
2008-01-10 15:51:07 -05:00
return $empty_array ;
2007-09-15 13:35:32 -04:00
}
2008-04-18 13:42:13 -04:00
// $args can be whatever, only use the args defined in defaults to compute the key
2008-07-01 11:54:58 -04:00
$filter_key = ( has_filter ( 'list_terms_exclusions' ) ) ? serialize ( $GLOBALS [ 'wp_filter' ][ 'list_terms_exclusions' ]) : '' ;
$key = md5 ( serialize ( compact ( array_keys ( $defaults )) ) . serialize ( $taxonomies ) . $filter_key );
2008-10-08 18:50:46 -04:00
$last_changed = wp_cache_get ( 'last_changed' , 'terms' );
if ( ! $last_changed ) {
$last_changed = time ();
wp_cache_set ( 'last_changed' , $last_changed , 'terms' );
}
$cache_key = " get_terms: $key : $last_changed " ;
2008-04-18 13:42:13 -04:00
2008-10-08 18:50:46 -04:00
if ( $cache = wp_cache_get ( $cache_key , 'terms' ) ) {
$terms = apply_filters ( 'get_terms' , $cache , $taxonomies , $args );
return $terms ;
2007-09-15 13:35:32 -04:00
}
if ( 'count' == $orderby )
$orderby = 'tt.count' ;
else if ( 'name' == $orderby )
$orderby = 't.name' ;
2007-10-23 12:39:03 -04:00
else if ( 'slug' == $orderby )
$orderby = 't.slug' ;
else if ( 'term_group' == $orderby )
$orderby = 't.term_group' ;
2007-09-15 13:35:32 -04:00
else
$orderby = 't.term_id' ;
$where = '' ;
$inclusions = '' ;
if ( ! empty ( $include ) ) {
$exclude = '' ;
2008-12-30 17:30:36 -05:00
$exclude_tree = '' ;
2007-09-15 13:35:32 -04:00
$interms = preg_split ( '/[\s,]+/' , $include );
if ( count ( $interms ) ) {
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $interms as $interm ) {
2007-09-15 13:35:32 -04:00
if ( empty ( $inclusions ))
$inclusions = ' AND ( t.term_id = ' . intval ( $interm ) . ' ' ;
else
$inclusions .= ' OR t.term_id = ' . intval ( $interm ) . ' ' ;
}
}
}
if ( ! empty ( $inclusions ) )
$inclusions .= ')' ;
$where .= $inclusions ;
$exclusions = '' ;
2008-12-30 17:30:36 -05:00
if ( ! empty ( $exclude_tree ) ) {
$excluded_trunks = preg_split ( '/[\s,]+/' , $exclude_tree );
foreach ( ( array ) $excluded_trunks as $extrunk ) {
$excluded_children = ( array ) get_terms ( $taxonomies [ 0 ], array ( 'child_of' => intval ( $extrunk ), 'fields' => 'ids' ));
$excluded_children [] = $extrunk ;
foreach ( ( array ) $excluded_children as $exterm ) {
if ( empty ( $exclusions ) )
$exclusions = ' AND ( t.term_id <> ' . intval ( $exterm ) . ' ' ;
else
$exclusions .= ' AND t.term_id <> ' . intval ( $exterm ) . ' ' ;
}
}
}
2007-09-15 13:35:32 -04:00
if ( ! empty ( $exclude ) ) {
$exterms = preg_split ( '/[\s,]+/' , $exclude );
if ( count ( $exterms ) ) {
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $exterms as $exterm ) {
2008-12-30 17:30:36 -05:00
if ( empty ( $exclusions ) )
2007-09-15 13:35:32 -04:00
$exclusions = ' AND ( t.term_id <> ' . intval ( $exterm ) . ' ' ;
else
$exclusions .= ' AND t.term_id <> ' . intval ( $exterm ) . ' ' ;
}
}
}
if ( ! empty ( $exclusions ) )
$exclusions .= ')' ;
$exclusions = apply_filters ( 'list_terms_exclusions' , $exclusions , $args );
$where .= $exclusions ;
if ( ! empty ( $slug ) ) {
$slug = sanitize_title ( $slug );
$where .= " AND t.slug = ' $slug ' " ;
}
if ( ! empty ( $name__like ) )
$where .= " AND t.name LIKE ' { $name__like } %' " ;
if ( '' != $parent ) {
$parent = ( int ) $parent ;
$where .= " AND tt.parent = ' $parent ' " ;
}
if ( $hide_empty && ! $hierarchical )
$where .= ' AND tt.count > 0' ;
2009-01-22 17:59:29 -05:00
// don't limit the query results when we have to descend the family tree
if ( ! empty ( $number ) && ! $hierarchical && empty ( $child_of ) && '' == $parent ) {
2008-01-25 14:29:01 -05:00
if ( $offset )
2009-01-22 17:59:29 -05:00
$limit = 'LIMIT ' . $offset . ',' . $number ;
2008-02-05 01:47:27 -05:00
else
2009-01-22 17:59:29 -05:00
$limit = 'LIMIT ' . $number ;
2008-02-05 01:47:27 -05:00
2008-01-25 14:29:01 -05:00
} else
2009-01-22 17:59:29 -05:00
$limit = '' ;
2007-09-15 13:35:32 -04:00
2008-02-12 04:02:02 -05:00
if ( ! empty ( $search ) ) {
$search = like_escape ( $search );
$where .= " AND (t.name LIKE '% $search %') " ;
}
2008-02-22 12:43:56 -05:00
$select_this = '' ;
2007-09-15 13:35:32 -04:00
if ( 'all' == $fields )
$select_this = 't.*, tt.*' ;
else if ( 'ids' == $fields )
2008-11-12 19:20:12 -05:00
$select_this = 't.term_id, tt.parent, tt.count' ;
2007-09-15 13:35:32 -04:00
else if ( 'names' == $fields )
2008-11-12 19:20:12 -05:00
$select_this = 't.term_id, tt.parent, tt.count, t.name' ;
2007-09-15 13:35:32 -04:00
2009-01-22 17:59:29 -05:00
$query = " SELECT $select_this FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE tt.taxonomy IN ( $in_taxonomies ) $where ORDER BY $orderby $order $limit " ;
2007-09-15 13:35:32 -04:00
2009-01-22 17:59:29 -05:00
$terms = $wpdb -> get_results ( $query );
2007-09-15 13:35:32 -04:00
if ( 'all' == $fields ) {
update_term_cache ( $terms );
}
2007-11-02 00:31:44 -04:00
if ( empty ( $terms ) ) {
$cache [ $key ] = array ();
wp_cache_set ( 'get_terms' , $cache , 'terms' );
2008-09-21 16:41:25 -04:00
$terms = apply_filters ( 'get_terms' , array (), $taxonomies , $args );
return $terms ;
2007-11-02 00:31:44 -04:00
}
2007-09-15 13:35:32 -04:00
2008-11-12 19:20:12 -05:00
if ( $child_of ) {
2007-09-15 13:35:32 -04:00
$children = _get_term_hierarchy ( $taxonomies [ 0 ]);
if ( ! empty ( $children ) )
$terms = & _get_term_children ( $child_of , $terms , $taxonomies [ 0 ]);
}
// Update term counts to include children.
2008-11-12 19:20:12 -05:00
if ( $pad_counts && 'all' == $fields )
2007-09-15 13:35:32 -04:00
_pad_term_counts ( $terms , $taxonomies [ 0 ]);
// Make sure we show empty categories that have children.
2008-08-06 16:31:54 -04:00
if ( $hierarchical && $hide_empty && is_array ( $terms ) ) {
2007-09-15 13:35:32 -04:00
foreach ( $terms as $k => $term ) {
if ( ! $term -> count ) {
$children = _get_term_children ( $term -> term_id , $terms , $taxonomies [ 0 ]);
2008-08-06 16:31:54 -04:00
if ( is_array ( $children ) )
foreach ( $children as $child )
if ( $child -> count )
continue 2 ;
2007-09-15 13:35:32 -04:00
// It really is empty
unset ( $terms [ $k ]);
}
}
}
reset ( $terms );
2008-12-09 13:03:31 -05:00
2008-11-12 19:20:12 -05:00
$_terms = array ();
if ( 'ids' == $fields ) {
while ( $term = array_shift ( $terms ) )
$_terms [] = $term -> term_id ;
$terms = $_terms ;
} elseif ( 'names' == $fields ) {
while ( $term = array_shift ( $terms ) )
$_terms [] = $term -> name ;
$terms = $_terms ;
}
2007-09-15 13:35:32 -04:00
2009-01-22 17:59:29 -05:00
if ( 0 < $number && intval ( @ count ( $terms )) > $number ) {
$terms = array_slice ( $terms , $offset , $number );
}
2008-10-08 18:50:46 -04:00
wp_cache_add ( $cache_key , $terms , 'terms' );
2007-09-15 13:35:32 -04:00
$terms = apply_filters ( 'get_terms' , $terms , $taxonomies , $args );
return $terms ;
}
/**
2008-06-22 16:23:23 -04:00
* Check if Term exists .
2007-09-15 13:35:32 -04:00
*
* Returns the index of a defined term , or 0 ( false ) if the term doesn ' t exist .
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
2007-09-15 13:35:32 -04:00
* @ param int | string $term The term to check
* @ param string $taxonomy The taxonomy name to use
* @ return mixed Get the term id or Term Object , if exists .
*/
function is_term ( $term , $taxonomy = '' ) {
global $wpdb ;
2008-07-24 15:28:40 -04:00
$select = " SELECT term_id FROM $wpdb->terms as t WHERE " ;
$tax_select = " SELECT tt.term_id, tt.term_taxonomy_id FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy as tt ON tt.term_id = t.term_id WHERE " ;
2007-09-15 13:35:32 -04:00
if ( is_int ( $term ) ) {
if ( 0 == $term )
return 0 ;
2008-07-17 12:59:40 -04:00
$where = 't.term_id = %d' ;
2008-07-24 15:28:40 -04:00
if ( ! empty ( $taxonomy ) )
return $wpdb -> get_row ( $wpdb -> prepare ( $tax_select . $where . " AND tt.taxonomy = %s " , $term , $taxonomy ), ARRAY_A );
else
return $wpdb -> get_var ( $wpdb -> prepare ( $select . $where , $term ) );
}
if ( '' === $slug = sanitize_title ( $term ) )
return 0 ;
$where = 't.slug = %s' ;
$else_where = 't.name = %s' ;
if ( ! empty ( $taxonomy ) ) {
if ( $result = $wpdb -> get_row ( $wpdb -> prepare ( " SELECT tt.term_id, tt.term_taxonomy_id FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy as tt ON tt.term_id = t.term_id WHERE $where AND tt.taxonomy = %s " , $slug , $taxonomy ), ARRAY_A ) )
return $result ;
2008-08-09 01:36:14 -04:00
2008-07-24 15:28:40 -04:00
return $wpdb -> get_row ( $wpdb -> prepare ( " SELECT tt.term_id, tt.term_taxonomy_id FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy as tt ON tt.term_id = t.term_id WHERE $else_where AND tt.taxonomy = %s " , $term , $taxonomy ), ARRAY_A );
2007-09-15 13:35:32 -04:00
}
2008-07-24 15:28:40 -04:00
if ( $result = $wpdb -> get_var ( $wpdb -> prepare ( " SELECT term_id FROM $wpdb->terms as t WHERE $where " , $slug ) ) )
return $result ;
2007-09-15 13:35:32 -04:00
2008-07-24 15:28:40 -04:00
return $wpdb -> get_var ( $wpdb -> prepare ( " SELECT term_id FROM $wpdb->terms as t WHERE $else_where " , $term ) );
2007-09-15 13:35:32 -04:00
}
/**
2008-06-22 16:23:23 -04:00
* Sanitize Term all fields .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* Relys on sanitize_term_field () to sanitize the term . The difference is that
* this function will sanitize < strong > all </ strong > fields . The context is based
* on sanitize_term_field () .
2007-09-15 13:35:32 -04:00
*
* The $term is expected to be either an array or an object .
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses sanitize_term_field Used to sanitize all fields in a term
2007-10-15 18:49:31 -04:00
*
2007-09-15 13:35:32 -04:00
* @ param array | object $term The term to check
* @ param string $taxonomy The taxonomy name to use
2007-10-21 13:18:24 -04:00
* @ param string $context Default is 'display' .
2007-09-15 13:35:32 -04:00
* @ return array | object Term with all fields sanitized
*/
function sanitize_term ( $term , $taxonomy , $context = 'display' ) {
2007-11-07 01:20:08 -05:00
if ( 'raw' == $context )
return $term ;
2007-09-15 13:35:32 -04:00
$fields = array ( 'term_id' , 'name' , 'description' , 'slug' , 'count' , 'parent' , 'term_group' );
$do_object = false ;
if ( is_object ( $term ) )
$do_object = true ;
2008-11-10 13:54:18 -05:00
$term_id = $do_object ? $term -> term_id : ( isset ( $term [ 'term_id' ]) ? $term [ 'term_id' ] : 0 );
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $fields as $field ) {
2008-11-10 13:54:18 -05:00
if ( $do_object ) {
if ( isset ( $term -> $field ) )
$term -> $field = sanitize_term_field ( $field , $term -> $field , $term_id , $taxonomy , $context );
} else {
if ( isset ( $term [ $field ]) )
$term [ $field ] = sanitize_term_field ( $field , $term [ $field ], $term_id , $taxonomy , $context );
}
2007-09-15 13:35:32 -04:00
}
2008-11-17 15:03:31 -05:00
if ( $do_object )
$term -> filter = $context ;
else
$term [ 'filter' ] = $context ;
2007-09-15 13:35:32 -04:00
return $term ;
}
/**
2008-06-22 16:23:23 -04:00
* Cleanse the field value in the term based on the context .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* Passing a term field value through the function should be assumed to have
* cleansed the value for whatever context the term field is going to be used .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* If no context or an unsupported context is given , then default filters will
* be applied .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* There are enough filters for each context to support a custom filtering
* without creating your own filter function . Simply create a function that
* hooks into the filter you need .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
2007-09-15 13:35:32 -04:00
* @ 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
*/
function sanitize_term_field ( $field , $value , $term_id , $taxonomy , $context ) {
2008-03-22 20:55:11 -04:00
if ( 'parent' == $field || 'term_id' == $field || 'count' == $field || 'term_group' == $field ) {
2007-09-15 13:35:32 -04:00
$value = ( int ) $value ;
2008-03-22 20:55:11 -04:00
if ( $value < 0 )
$value = 0 ;
}
2007-09-15 13:35:32 -04:00
2007-11-03 15:06:43 -04:00
if ( 'raw' == $context )
return $value ;
2007-09-15 13:35:32 -04:00
if ( 'edit' == $context ) {
$value = apply_filters ( " edit_term_ $field " , $value , $term_id , $taxonomy );
$value = apply_filters ( " edit_ ${ taxonomy } _ $field " , $value , $term_id );
if ( 'description' == $field )
$value = format_to_edit ( $value );
else
$value = attribute_escape ( $value );
} else if ( 'db' == $context ) {
$value = apply_filters ( " pre_term_ $field " , $value , $taxonomy );
$value = apply_filters ( " pre_ ${ taxonomy } _ $field " , $value );
2007-09-22 14:01:08 -04:00
// Back compat filters
if ( 'slug' == $field )
$value = apply_filters ( 'pre_category_nicename' , $value );
2008-02-05 01:47:27 -05:00
2007-09-15 13:35:32 -04:00
} else if ( 'rss' == $context ) {
$value = apply_filters ( " term_ ${ field } _rss " , $value , $taxonomy );
2008-01-04 14:36:34 -05:00
$value = apply_filters ( " ${ taxonomy}_${field } _rss " , $value );
2007-09-15 13:35:32 -04:00
} else {
// Use display filters by default.
$value = apply_filters ( " term_ $field " , $value , $term_id , $taxonomy , $context );
$value = apply_filters ( " ${ taxonomy } _ $field " , $value , $term_id , $context );
}
if ( 'attribute' == $context )
$value = attribute_escape ( $value );
else if ( 'js' == $context )
$value = js_escape ( $value );
return $value ;
}
/**
2008-06-22 16:23:23 -04:00
* Count how many terms are in Taxonomy .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* Default $args is 'ignore_empty' which can be < code > 'ignore_empty=true' </ code >
* or < code > array ( 'ignore_empty' => true ); </ code >.
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ uses $wpdb
* @ uses wp_parse_args () Turns strings into arrays and merges defaults into an array .
2007-10-15 18:49:31 -04:00
*
2007-09-15 13:35:32 -04:00
* @ param string $taxonomy Taxonomy name
* @ param array | string $args Overwrite defaults
* @ return int How many terms are in $taxonomy
*/
function wp_count_terms ( $taxonomy , $args = array () ) {
global $wpdb ;
$defaults = array ( 'ignore_empty' => false );
$args = wp_parse_args ( $args , $defaults );
extract ( $args , EXTR_SKIP );
$where = '' ;
if ( $ignore_empty )
$where = 'AND count > 0' ;
2008-04-14 12:13:25 -04:00
return $wpdb -> get_var ( $wpdb -> prepare ( " SELECT COUNT(*) FROM $wpdb->term_taxonomy WHERE taxonomy = %s $where " , $taxonomy ) );
2007-09-15 13:35:32 -04:00
}
/**
2008-06-22 16:23:23 -04:00
* Will unlink the term from the taxonomy .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* Will remove the term ' s relationship to the taxonomy , not the term or taxonomy
* itself . The term and taxonomy will still exist . Will require the term ' s
* object ID to perform the operation .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
2007-10-21 13:18:24 -04:00
* @ param int $object_id The term Object Id that refers to the term
2007-09-15 13:35:32 -04:00
* @ param string | array $taxonomy List of Taxonomy Names or single Taxonomy name .
*/
function wp_delete_object_term_relationships ( $object_id , $taxonomies ) {
global $wpdb ;
$object_id = ( int ) $object_id ;
if ( ! is_array ( $taxonomies ) )
$taxonomies = array ( $taxonomies );
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $taxonomies as $taxonomy ) {
2008-10-25 18:56:02 -04:00
$tt_ids = wp_get_object_terms ( $object_id , $taxonomy , 'fields=tt_ids' );
$in_tt_ids = " ' " . implode ( " ', ' " , $tt_ids ) . " ' " ;
$wpdb -> query ( $wpdb -> prepare ( " DELETE FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id IN ( $in_tt_ids ) " , $object_id ) );
wp_update_term_count ( $tt_ids , $taxonomy );
2007-09-15 13:35:32 -04:00
}
}
/**
2008-06-22 16:23:23 -04:00
* Removes a term from the database .
2007-10-15 18:49:31 -04:00
*
2008-06-22 16:23:23 -04:00
* If the term is a parent of other terms , then the children will be updated to
* that term ' s parent .
2007-12-13 19:25:39 -05:00
*
* The $args 'default' will only override the terms found , if there is only one
* term found . Any other and the found terms are used .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-12-13 19:25:39 -05:00
*
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2008-06-22 16:23:23 -04:00
* @ uses do_action () Calls both 'delete_term' and 'delete_$taxonomy' action
* hooks , passing term object , term id . 'delete_term' gets an additional
* parameter with the $taxonomy parameter .
2007-10-15 18:49:31 -04:00
*
* @ param int $term Term ID
* @ param string $taxonomy Taxonomy Name
2007-12-13 19:25:39 -05:00
* @ 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 .
2007-09-15 13:35:32 -04:00
*/
function wp_delete_term ( $term , $taxonomy , $args = array () ) {
global $wpdb ;
$term = ( int ) $term ;
if ( ! $ids = is_term ( $term , $taxonomy ) )
return false ;
2007-10-28 17:33:03 -04:00
if ( is_wp_error ( $ids ) )
return $ids ;
2007-09-15 13:35:32 -04:00
$tt_id = $ids [ 'term_taxonomy_id' ];
$defaults = array ();
$args = wp_parse_args ( $args , $defaults );
extract ( $args , EXTR_SKIP );
if ( isset ( $default ) ) {
$default = ( int ) $default ;
if ( ! is_term ( $default , $taxonomy ) )
unset ( $default );
}
// Update children to point to new parent
if ( is_taxonomy_hierarchical ( $taxonomy ) ) {
$term_obj = get_term ( $term , $taxonomy );
2007-09-18 12:32:22 -04:00
if ( is_wp_error ( $term_obj ) )
return $term_obj ;
2007-09-15 13:35:32 -04:00
$parent = $term_obj -> parent ;
2007-10-25 03:15:02 -04:00
$wpdb -> update ( $wpdb -> term_taxonomy , compact ( 'parent' ), array ( 'parent' => $term_obj -> term_id ) + compact ( 'taxonomy' ) );
2007-09-15 13:35:32 -04:00
}
2007-10-12 23:51:11 -04:00
$objects = $wpdb -> get_col ( $wpdb -> prepare ( " SELECT object_id FROM $wpdb->term_relationships WHERE term_taxonomy_id = %d " , $tt_id ) );
2007-09-15 13:35:32 -04:00
foreach ( ( array ) $objects as $object ) {
$terms = wp_get_object_terms ( $object , $taxonomy , 'fields=ids' );
if ( 1 == count ( $terms ) && isset ( $default ) )
$terms = array ( $default );
else
$terms = array_diff ( $terms , array ( $term ));
$terms = array_map ( 'intval' , $terms );
wp_set_object_terms ( $object , $terms , $taxonomy );
}
2007-10-12 23:51:11 -04:00
$wpdb -> query ( $wpdb -> prepare ( " DELETE FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d " , $tt_id ) );
2007-09-15 13:35:32 -04:00
// Delete the term if no taxonomies use it.
2007-10-12 23:51:11 -04:00
if ( ! $wpdb -> get_var ( $wpdb -> prepare ( " SELECT COUNT(*) FROM $wpdb->term_taxonomy WHERE term_id = %d " , $term ) ) )
$wpdb -> query ( $wpdb -> prepare ( " DELETE FROM $wpdb->terms WHERE term_id = %d " , $term ) );
2007-09-15 13:35:32 -04:00
clean_term_cache ( $term , $taxonomy );
2007-10-14 00:55:33 -04:00
do_action ( 'delete_term' , $term , $tt_id , $taxonomy );
2007-09-15 13:35:32 -04:00
do_action ( " delete_ $taxonomy " , $term , $tt_id );
return true ;
}
/**
2008-06-22 16:23:23 -04:00
* Retrieves the terms associated with the given object ( s ), in the supplied taxonomies .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* The following information has to do the $args parameter and for what can be
* contained in the string or array of that parameter , if it exists .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* The first argument is called , 'orderby' and has the default value of 'name' .
* The other value that is supported is 'count' .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* The second argument is called , 'order' and has the default value of 'ASC' .
* The only other value that will be acceptable is 'DESC' .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* The final argument supported is called , 'fields' and has the default value of
* 'all' . There are multiple other options that can be used instead . Supported
* values are as follows : 'all' , 'ids' , 'names' , and finally
* 'all_with_object_id' .
2007-10-15 18:49:31 -04:00
*
2008-06-22 16:23:23 -04:00
* The fields argument also decides what will be returned . If 'all' or
* 'all_with_object_id' is choosen or the default kept intact , then all matching
* terms objects will be returned . If either 'ids' or 'names' is used , then an
* array of all matching term ids or term names will be returned respectively .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
2007-12-13 19:25:39 -05:00
* @ param int | array $object_id The id of the object ( s ) to retrieve .
2007-09-15 13:35:32 -04:00
* @ param string | array $taxonomies The taxonomies to retrieve terms from .
2007-10-15 18:49:31 -04:00
* @ param array | string $args Change what is returned
2007-10-21 13:18:24 -04:00
* @ return array | WP_Error The requested term data or empty array if no terms found . WP_Error if $taxonomy does not exist .
2007-09-15 13:35:32 -04:00
*/
function wp_get_object_terms ( $object_ids , $taxonomies , $args = array ()) {
global $wpdb ;
if ( ! is_array ( $taxonomies ) )
$taxonomies = array ( $taxonomies );
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $taxonomies as $taxonomy ) {
2007-09-15 13:35:32 -04:00
if ( ! is_taxonomy ( $taxonomy ) )
return new WP_Error ( 'invalid_taxonomy' , __ ( 'Invalid Taxonomy' ));
}
if ( ! is_array ( $object_ids ) )
$object_ids = array ( $object_ids );
$object_ids = array_map ( 'intval' , $object_ids );
$defaults = array ( 'orderby' => 'name' , 'order' => 'ASC' , 'fields' => 'all' );
$args = wp_parse_args ( $args , $defaults );
2008-03-26 02:37:19 -04:00
$terms = array ();
if ( count ( $taxonomies ) > 1 ) {
foreach ( $taxonomies as $index => $taxonomy ) {
$t = get_taxonomy ( $taxonomy );
2008-05-19 14:47:33 -04:00
if ( isset ( $t -> args ) && is_array ( $t -> args ) && $args != array_merge ( $args , $t -> args ) ) {
2008-03-26 02:37:19 -04:00
unset ( $taxonomies [ $index ]);
$terms = array_merge ( $terms , wp_get_object_terms ( $object_ids , $taxonomy , array_merge ( $args , $t -> args )));
}
}
} else {
$t = get_taxonomy ( $taxonomies [ 0 ]);
2008-05-19 14:47:33 -04:00
if ( isset ( $t -> args ) && is_array ( $t -> args ) )
2008-03-26 02:37:19 -04:00
$args = array_merge ( $args , $t -> args );
}
2007-09-15 13:35:32 -04:00
extract ( $args , EXTR_SKIP );
if ( 'count' == $orderby )
$orderby = 'tt.count' ;
else if ( 'name' == $orderby )
$orderby = 't.name' ;
2008-02-14 00:40:19 -05:00
else if ( 'slug' == $orderby )
$orderby = 't.slug' ;
else if ( 'term_group' == $orderby )
$orderby = 't.term_group' ;
2008-02-14 12:17:57 -05:00
else if ( 'term_order' == $orderby )
$orderby = 'tr.term_order' ;
2008-02-14 00:40:19 -05:00
else
$orderby = 't.term_id' ;
2007-09-15 13:35:32 -04:00
$taxonomies = " ' " . implode ( " ', ' " , $taxonomies ) . " ' " ;
$object_ids = implode ( ', ' , $object_ids );
2008-02-22 12:43:56 -05:00
$select_this = '' ;
2007-09-15 13:35:32 -04:00
if ( 'all' == $fields )
$select_this = 't.*, tt.*' ;
else if ( 'ids' == $fields )
$select_this = 't.term_id' ;
2008-02-05 01:47:27 -05:00
else if ( 'names' == $fields )
2007-09-15 22:36:23 -04:00
$select_this = 't.name' ;
2007-09-15 13:35:32 -04:00
else if ( 'all_with_object_id' == $fields )
$select_this = 't.*, tt.*, tr.object_id' ;
$query = " SELECT $select_this FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON tt.term_id = t.term_id INNER JOIN $wpdb->term_relationships AS tr ON tr.term_taxonomy_id = tt.term_taxonomy_id WHERE tt.taxonomy IN ( $taxonomies ) AND tr.object_id IN ( $object_ids ) ORDER BY $orderby $order " ;
if ( 'all' == $fields || 'all_with_object_id' == $fields ) {
2008-03-26 02:37:19 -04:00
$terms = array_merge ( $terms , $wpdb -> get_results ( $query ));
2007-09-15 13:35:32 -04:00
update_term_cache ( $terms );
2007-09-15 22:36:23 -04:00
} else if ( 'ids' == $fields || 'names' == $fields ) {
2008-03-26 02:37:19 -04:00
$terms = array_merge ( $terms , $wpdb -> get_col ( $query ));
2007-09-15 13:35:32 -04:00
} else if ( 'tt_ids' == $fields ) {
$terms = $wpdb -> get_col ( " SELECT tr.term_taxonomy_id FROM $wpdb->term_relationships AS tr INNER JOIN $wpdb->term_taxonomy AS tt ON tr.term_taxonomy_id = tt.term_taxonomy_id WHERE tr.object_id IN ( $object_ids ) AND tt.taxonomy IN ( $taxonomies ) ORDER BY tr.term_taxonomy_id $order " );
}
if ( ! $terms )
return array ();
return $terms ;
}
/**
2008-06-22 16:23:23 -04:00
* Adds a new term to the database . Optionally marks it as an alias of an existing term .
2007-09-15 13:35:32 -04:00
*
2008-06-22 16:23:23 -04:00
* Error handling is assigned for the nonexistance of the $taxonomy and $term
* parameters before inserting . If both the term id and taxonomy exist
* previously , then an array will be returned that contains the term id and the
* contents of what is returned . The keys of the array are 'term_id' and
* 'term_taxonomy_id' containing numeric values .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* It is assumed that the term does not yet exist or the above will apply . The
* term will be first added to the term table and then related to the taxonomy
* if everything is well . If everything is correct , then several actions will be
* run prior to a filter and then several actions will be run after the filter
* is run .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* The arguments decide how the term is handled based on the $args parameter .
* The following is a list of the available overrides and the defaults .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* 'alias_of' . There is no default , but if added , expected is the slug that the
* term will be an alias of . Expected to be a string .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* 'description' . There is no default . If exists , will be added to the database
* along with the term . Expected to be a string .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* 'parent' . Expected to be numeric and default is 0 ( zero ) . Will assign value
* of 'parent' to the term .
2007-12-13 19:25:39 -05:00
*
* 'slug' . Expected to be a string . There is no default .
*
2008-06-22 16:23:23 -04:00
* If 'slug' argument exists then the slug will be checked to see if it is not
* a valid term . If that check succeeds ( it is not a valid term ), then it is
* added and the term id is given . If it fails , then a check is made to whether
* the taxonomy is hierarchical and the parent argument is not empty . If the
* second check succeeds , the term will be inserted and the term id will be
* given .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
2007-12-13 19:25:39 -05:00
* @ uses do_action () Calls 'create_term' hook with the term id and taxonomy id as parameters .
* @ uses do_action () Calls 'create_$taxonomy' hook with term id and taxonomy id as parameters .
* @ uses apply_filters () Calls 'term_id_filter' hook with term id and taxonomy id as parameters .
* @ uses do_action () Calls 'created_term' hook with the term id and taxonomy id as parameters .
* @ uses do_action () Calls 'created_$taxonomy' hook with term id and taxonomy id as parameters .
*
2007-09-15 13:35:32 -04:00
* @ param int | string $term The term to add or update .
* @ param string $taxonomy The taxonomy to which to add the term
* @ param array | string $args Change the values of the inserted term
2007-10-21 13:18:24 -04:00
* @ return array | WP_Error The Term ID and Term Taxonomy ID
2007-09-15 13:35:32 -04:00
*/
function wp_insert_term ( $term , $taxonomy , $args = array () ) {
global $wpdb ;
if ( ! is_taxonomy ( $taxonomy ) )
return new WP_Error ( 'invalid_taxonomy' , __ ( 'Invalid taxonomy' ));
if ( is_int ( $term ) && 0 == $term )
return new WP_Error ( 'invalid_term_id' , __ ( 'Invalid term ID' ));
2008-07-21 17:53:32 -04:00
if ( '' == trim ( $term ) )
return new WP_Error ( 'empty_term_name' , __ ( 'A name is required for this term' ));
2007-09-15 13:35:32 -04:00
$defaults = array ( 'alias_of' => '' , 'description' => '' , 'parent' => 0 , 'slug' => '' );
$args = wp_parse_args ( $args , $defaults );
$args [ 'name' ] = $term ;
2007-09-22 14:01:08 -04:00
$args [ 'taxonomy' ] = $taxonomy ;
2007-09-15 13:35:32 -04:00
$args = sanitize_term ( $args , $taxonomy , 'db' );
extract ( $args , EXTR_SKIP );
2007-10-17 16:41:43 -04:00
// expected_slashed ($name)
$name = stripslashes ( $name );
2007-10-26 15:44:57 -04:00
$description = stripslashes ( $description );
2007-10-17 16:41:43 -04:00
2007-09-15 13:35:32 -04:00
if ( empty ( $slug ) )
$slug = sanitize_title ( $name );
$term_group = 0 ;
if ( $alias_of ) {
2007-10-23 12:36:08 -04:00
$alias = $wpdb -> get_row ( $wpdb -> prepare ( " SELECT term_id, term_group FROM $wpdb->terms WHERE slug = %s " , $alias_of ) );
2007-09-15 13:35:32 -04:00
if ( $alias -> term_group ) {
// The alias we want is already in a group, so let's use that one.
$term_group = $alias -> term_group ;
} else {
// The alias isn't in a group, so let's create a new one and firstly add the alias term to it.
2007-10-23 12:43:15 -04:00
$term_group = $wpdb -> get_var ( " SELECT MAX(term_group) FROM $wpdb->terms " ) + 1 ;
2007-10-12 23:51:11 -04:00
$wpdb -> query ( $wpdb -> prepare ( " UPDATE $wpdb->terms SET term_group = %d WHERE term_id = %d " , $term_group , $alias -> term_id ) );
2007-09-15 13:35:32 -04:00
}
}
if ( ! $term_id = is_term ( $slug ) ) {
2008-03-20 18:33:34 -04:00
if ( false === $wpdb -> insert ( $wpdb -> terms , compact ( 'name' , 'slug' , 'term_group' ) ) )
2008-03-20 19:34:32 -04:00
return new WP_Error ( 'db_insert_error' , __ ( 'Could not insert term into the database' ), $wpdb -> last_error );
2007-09-15 13:35:32 -04:00
$term_id = ( int ) $wpdb -> insert_id ;
2007-09-22 14:01:08 -04:00
} else if ( is_taxonomy_hierarchical ( $taxonomy ) && ! empty ( $parent ) ) {
// If the taxonomy supports hierarchy and the term has a parent, make the slug unique
// by incorporating parent slugs.
$slug = wp_unique_term_slug ( $slug , ( object ) $args );
2008-03-20 18:33:34 -04:00
if ( false === $wpdb -> insert ( $wpdb -> terms , compact ( 'name' , 'slug' , 'term_group' ) ) )
2008-03-20 19:34:32 -04:00
return new WP_Error ( 'db_insert_error' , __ ( 'Could not insert term into the database' ), $wpdb -> last_error );
2007-09-22 14:01:08 -04:00
$term_id = ( int ) $wpdb -> insert_id ;
2007-09-15 13:35:32 -04:00
}
if ( empty ( $slug ) ) {
$slug = sanitize_title ( $slug , $term_id );
2007-10-12 23:51:11 -04:00
$wpdb -> update ( $wpdb -> terms , compact ( 'slug' ), compact ( 'term_id' ) );
2007-09-15 13:35:32 -04:00
}
2007-10-12 23:51:11 -04:00
$tt_id = $wpdb -> get_var ( $wpdb -> prepare ( " SELECT tt.term_taxonomy_id FROM $wpdb->term_taxonomy AS tt INNER JOIN $wpdb->terms AS t ON tt.term_id = t.term_id WHERE tt.taxonomy = %s AND t.term_id = %d " , $taxonomy , $term_id ) );
2007-09-15 13:35:32 -04:00
if ( ! empty ( $tt_id ) )
return array ( 'term_id' => $term_id , 'term_taxonomy_id' => $tt_id );
2007-10-12 23:51:11 -04:00
$wpdb -> insert ( $wpdb -> term_taxonomy , compact ( 'term_id' , 'taxonomy' , 'description' , 'parent' ) + array ( 'count' => 0 ) );
2007-09-15 13:35:32 -04:00
$tt_id = ( int ) $wpdb -> insert_id ;
do_action ( " create_term " , $term_id , $tt_id );
do_action ( " create_ $taxonomy " , $term_id , $tt_id );
$term_id = apply_filters ( 'term_id_filter' , $term_id , $tt_id );
clean_term_cache ( $term_id , $taxonomy );
do_action ( " created_term " , $term_id , $tt_id );
do_action ( " created_ $taxonomy " , $term_id , $tt_id );
return array ( 'term_id' => $term_id , 'term_taxonomy_id' => $tt_id );
}
/**
2008-06-22 16:23:23 -04:00
* Create Term and Taxonomy Relationships .
2008-02-05 01:47:27 -05:00
*
2008-06-22 16:23:23 -04:00
* Relates an object ( post , link etc ) to a term and taxonomy type . Creates the
* term and taxonomy relationship if it doesn ' t already exist . Creates a term if
* it doesn ' t exist ( using the slug ) .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* A relationship means that the term is grouped in or belongs to the taxonomy .
* A term has no meaning until it is given context by defining which taxonomy it
* exists under .
2007-09-15 13:35:32 -04:00
*
2007-10-15 18:49:31 -04:00
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
2007-09-15 13:35:32 -04:00
* @ param int $object_id The object to relate to .
* @ param array | int | string $term The slug or id of the term .
* @ param array | string $taxonomy The context in which to relate the term to the object .
* @ param bool $append If false will delete difference of terms .
2007-10-21 13:18:24 -04:00
* @ return array | WP_Error Affected Term IDs
2007-09-15 13:35:32 -04:00
*/
function wp_set_object_terms ( $object_id , $terms , $taxonomy , $append = false ) {
global $wpdb ;
$object_id = ( int ) $object_id ;
if ( ! is_taxonomy ( $taxonomy ) )
return new WP_Error ( 'invalid_taxonomy' , __ ( 'Invalid Taxonomy' ));
if ( ! is_array ( $terms ) )
$terms = array ( $terms );
if ( ! $append )
2008-10-25 18:56:02 -04:00
$old_tt_ids = wp_get_object_terms ( $object_id , $taxonomy , 'fields=tt_ids' );
2007-09-15 13:35:32 -04:00
$tt_ids = array ();
$term_ids = array ();
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $terms as $term ) {
2007-12-19 18:25:11 -05:00
if ( ! strlen ( trim ( $term )) )
continue ;
2008-02-05 01:47:27 -05:00
2008-10-25 18:56:02 -04:00
if ( ! $term_info = is_term ( $term , $taxonomy ) )
$term_info = wp_insert_term ( $term , $taxonomy );
if ( is_wp_error ( $term_info ) )
return $term_info ;
$term_ids [] = $term_info [ 'term_id' ];
$tt_id = $term_info [ 'term_taxonomy_id' ];
$tt_ids [] = $tt_id ;
2007-09-15 13:35:32 -04:00
2008-10-25 18:56:02 -04:00
if ( $wpdb -> get_var ( $wpdb -> prepare ( " SELECT term_taxonomy_id FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id = %d " , $object_id , $tt_id ) ) )
2007-09-15 13:35:32 -04:00
continue ;
2008-10-25 18:56:02 -04:00
$wpdb -> insert ( $wpdb -> term_relationships , array ( 'object_id' => $object_id , 'term_taxonomy_id' => $tt_id ) );
2007-09-15 13:35:32 -04:00
}
wp_update_term_count ( $tt_ids , $taxonomy );
if ( ! $append ) {
2008-10-25 18:56:02 -04:00
$delete_terms = array_diff ( $old_tt_ids , $tt_ids );
2007-09-15 13:35:32 -04:00
if ( $delete_terms ) {
$in_delete_terms = " ' " . implode ( " ', ' " , $delete_terms ) . " ' " ;
2008-04-14 12:13:25 -04:00
$wpdb -> query ( $wpdb -> prepare ( " DELETE FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id IN ( $in_delete_terms ) " , $object_id ) );
2007-09-15 13:35:32 -04:00
wp_update_term_count ( $delete_terms , $taxonomy );
}
}
2008-02-14 12:17:57 -05:00
$t = get_taxonomy ( $taxonomy );
2008-02-22 12:43:56 -05:00
if ( ! $append && isset ( $t -> sort ) && $t -> sort ) {
2008-02-14 12:17:57 -05:00
$values = array ();
$term_order = 0 ;
2008-05-15 21:43:35 -04:00
$final_tt_ids = wp_get_object_terms ( $object_id , $taxonomy , 'fields=tt_ids' );
foreach ( $tt_ids as $tt_id )
if ( in_array ( $tt_id , $final_tt_ids ) )
$values [] = $wpdb -> prepare ( " (%d, %d, %d) " , $object_id , $tt_id , ++ $term_order );
2008-02-14 12:17:57 -05:00
if ( $values )
$wpdb -> query ( " INSERT INTO $wpdb->term_relationships (object_id, term_taxonomy_id, term_order) VALUES " . join ( ',' , $values ) . " ON DUPLICATE KEY UPDATE term_order = VALUES(term_order) " );
}
2007-09-15 13:35:32 -04:00
return $tt_ids ;
}
2007-10-15 18:49:31 -04:00
/**
2008-06-22 16:23:23 -04:00
* Will make slug unique , if it isn ' t already .
2008-02-05 01:47:27 -05:00
*
2008-06-22 16:23:23 -04:00
* 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 .
2007-10-15 18:49:31 -04:00
*
2008-06-22 16:23:23 -04:00
* The way this works is that if the taxonomy that the term belongs to is
* heirarchical and has a parent , it will append that parent to the $slug .
2007-10-15 18:49:31 -04:00
*
2008-06-22 16:23:23 -04:00
* If that still doesn ' t return an unique slug , then it try to append a number
* until it finds a number that is truely unique .
2008-02-05 01:47:27 -05:00
*
2007-10-21 13:18:24 -04:00
* The only purpose for $term is for appending a parent , if one exists .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
* @ 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 .
*/
2007-09-22 14:01:08 -04:00
function wp_unique_term_slug ( $slug , $term ) {
global $wpdb ;
// 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 ) ) {
$parent_term = get_term ( $the_parent , $term -> taxonomy );
if ( is_wp_error ( $parent_term ) || empty ( $parent_term ) )
break ;
$slug .= '-' . $parent_term -> slug ;
if ( empty ( $parent_term -> parent ) )
break ;
$the_parent = $parent_term -> parent ;
}
}
// If we didn't get a unique slug, try appending a number to make it unique.
2007-11-09 13:34:41 -05:00
if ( ! empty ( $args [ 'term_id' ]) )
$query = $wpdb -> prepare ( " SELECT slug FROM $wpdb->terms WHERE slug = %s AND term_id != %d " , $slug , $args [ 'term_id' ] );
else
2007-12-06 14:49:33 -05:00
$query = $wpdb -> prepare ( " SELECT slug FROM $wpdb->terms WHERE slug = %s " , $slug );
2007-11-09 13:34:41 -05:00
if ( $wpdb -> get_var ( $query ) ) {
2007-09-22 14:01:08 -04:00
$num = 2 ;
do {
$alt_slug = $slug . " - $num " ;
$num ++ ;
2007-10-12 23:51:11 -04:00
$slug_check = $wpdb -> get_var ( $wpdb -> prepare ( " SELECT slug FROM $wpdb->terms WHERE slug = %s " , $alt_slug ) );
2007-09-22 14:01:08 -04:00
} while ( $slug_check );
$slug = $alt_slug ;
}
return $slug ;
}
2007-10-15 18:49:31 -04:00
/**
2008-06-22 16:23:23 -04:00
* Update term based on arguments provided .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* The $args will indiscriminately override all values with the same field name .
* Care must be taken to not override important information need to update or
* update will fail ( or perhaps create a new term , neither would be acceptable ) .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* Defaults will set 'alias_of' , 'description' , 'parent' , and 'slug' if not
* defined in $args already .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* 'alias_of' will create a term group , if it doesn ' t already exist , and update
* it for the $term .
2007-12-13 19:25:39 -05:00
*
2008-06-22 16:23:23 -04:00
* If the 'slug' argument in $args is missing , then the 'name' in $args will be
* used . It should also be noted that if you set 'slug' and it isn ' t unique then
* a WP_Error will be passed back . If you don ' t pass any slug , then a unique one
* will be created for you .
2007-10-21 13:18:24 -04:00
*
2008-06-22 16:23:23 -04:00
* For what can be overrode in $args , check the term scheme can contain and stay
* away from the term keys .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-12-13 19:25:39 -05:00
*
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-12-13 19:25:39 -05:00
* @ uses do_action () Will call both 'edit_term' and 'edit_$taxonomy' twice .
2008-06-22 16:23:23 -04:00
* @ uses apply_filters () Will call the 'term_id_filter' filter and pass the term
* id and taxonomy id .
2007-10-15 18:49:31 -04:00
*
* @ param int $term The ID of the term
* @ param string $taxonomy The context in which to relate the term to the object .
2007-12-13 19:25:39 -05:00
* @ param array | string $args Overwrite term field values
* @ return array | WP_Error Returns Term ID and Taxonomy Term ID
2007-10-15 18:49:31 -04:00
*/
2007-09-15 13:35:32 -04:00
function wp_update_term ( $term , $taxonomy , $args = array () ) {
global $wpdb ;
if ( ! is_taxonomy ( $taxonomy ) )
return new WP_Error ( 'invalid_taxonomy' , __ ( 'Invalid taxonomy' ));
$term_id = ( int ) $term ;
// First, get all of the original args
$term = get_term ( $term_id , $taxonomy , ARRAY_A );
// Escape data pulled from DB.
$term = add_magic_quotes ( $term );
// Merge old and new args with new args overwriting old ones.
$args = array_merge ( $term , $args );
$defaults = array ( 'alias_of' => '' , 'description' => '' , 'parent' => 0 , 'slug' => '' );
$args = wp_parse_args ( $args , $defaults );
$args = sanitize_term ( $args , $taxonomy , 'db' );
extract ( $args , EXTR_SKIP );
2007-10-26 15:44:57 -04:00
// expected_slashed ($name)
$name = stripslashes ( $name );
$description = stripslashes ( $description );
2008-07-21 17:53:32 -04:00
if ( '' == trim ( $name ) )
return new WP_Error ( 'empty_term_name' , __ ( 'A name is required for this term' ));
2007-09-22 14:01:08 -04:00
$empty_slug = false ;
if ( empty ( $slug ) ) {
$empty_slug = true ;
2007-09-15 13:35:32 -04:00
$slug = sanitize_title ( $name );
2007-09-22 14:01:08 -04:00
}
2007-09-15 13:35:32 -04:00
if ( $alias_of ) {
2007-10-23 12:36:08 -04:00
$alias = $wpdb -> get_row ( $wpdb -> prepare ( " SELECT term_id, term_group FROM $wpdb->terms WHERE slug = %s " , $alias_of ) );
2007-09-15 13:35:32 -04:00
if ( $alias -> term_group ) {
// The alias we want is already in a group, so let's use that one.
$term_group = $alias -> term_group ;
} else {
// The alias isn't in a group, so let's create a new one and firstly add the alias term to it.
2007-10-23 12:43:15 -04:00
$term_group = $wpdb -> get_var ( " SELECT MAX(term_group) FROM $wpdb->terms " ) + 1 ;
2007-10-12 23:51:11 -04:00
$wpdb -> update ( $wpdb -> terms , compact ( 'term_group' ), array ( 'term_id' => $alias -> term_id ) );
2007-09-15 13:35:32 -04:00
}
}
2007-09-22 14:01:08 -04:00
// Check for duplicate slug
2007-10-12 23:51:11 -04:00
$id = $wpdb -> get_var ( $wpdb -> prepare ( " SELECT term_id FROM $wpdb->terms WHERE slug = %s " , $slug ) );
2007-09-22 14:01:08 -04:00
if ( $id && ( $id != $term_id ) ) {
2007-11-09 13:34:41 -05:00
// If an empty slug was passed or the parent changed, reset the slug to something unique.
2007-09-22 14:01:08 -04:00
// Otherwise, bail.
2007-11-09 13:34:41 -05:00
if ( $empty_slug || ( $parent != $term -> parent ) )
2007-09-22 14:01:08 -04:00
$slug = wp_unique_term_slug ( $slug , ( object ) $args );
else
return new WP_Error ( 'duplicate_term_slug' , sprintf ( __ ( 'The slug "%s" is already in use by another term' ), $slug ));
}
2007-10-12 23:51:11 -04:00
$wpdb -> update ( $wpdb -> terms , compact ( 'name' , 'slug' , 'term_group' ), compact ( 'term_id' ) );
2007-09-15 13:35:32 -04:00
if ( empty ( $slug ) ) {
$slug = sanitize_title ( $name , $term_id );
2007-10-12 23:51:11 -04:00
$wpdb -> update ( $wpdb -> terms , compact ( 'slug' ), compact ( 'term_id' ) );
2007-09-15 13:35:32 -04:00
}
2007-10-12 23:51:11 -04:00
$tt_id = $wpdb -> get_var ( $wpdb -> prepare ( " SELECT tt.term_taxonomy_id FROM $wpdb->term_taxonomy AS tt INNER JOIN $wpdb->terms AS t ON tt.term_id = t.term_id WHERE tt.taxonomy = %s AND t.term_id = %d " , $taxonomy , $term_id ) );
2007-09-15 13:35:32 -04:00
2007-10-15 16:07:29 -04:00
$wpdb -> update ( $wpdb -> term_taxonomy , compact ( 'term_id' , 'taxonomy' , 'description' , 'parent' ), array ( 'term_taxonomy_id' => $tt_id ) );
2007-09-15 13:35:32 -04:00
do_action ( " edit_term " , $term_id , $tt_id );
do_action ( " edit_ $taxonomy " , $term_id , $tt_id );
$term_id = apply_filters ( 'term_id_filter' , $term_id , $tt_id );
clean_term_cache ( $term_id , $taxonomy );
do_action ( " edited_term " , $term_id , $tt_id );
do_action ( " edited_ $taxonomy " , $term_id , $tt_id );
return array ( 'term_id' => $term_id , 'term_taxonomy_id' => $tt_id );
}
2008-06-22 16:23:23 -04:00
/**
* Enable or disable term counting .
*
2008-08-30 17:23:43 -04:00
* @ since 2.5 . 0
2008-06-22 16:23:23 -04:00
*
2008-08-30 17:23:43 -04:00
* @ param bool $defer Optional . Enable if true , disable if false .
* @ return bool Whether term counting is enabled or disabled .
2008-06-22 16:23:23 -04:00
*/
2008-08-30 17:23:43 -04:00
function wp_defer_term_counting ( $defer = null ) {
2007-12-12 00:14:00 -05:00
static $_defer = false ;
2008-02-05 01:47:27 -05:00
2007-12-12 00:14:00 -05:00
if ( is_bool ( $defer ) ) {
$_defer = $defer ;
// flush any deferred counts
if ( ! $defer )
2008-08-30 17:23:43 -04:00
wp_update_term_count ( null , null , true );
2007-12-12 00:14:00 -05:00
}
2008-02-05 01:47:27 -05:00
2007-12-12 00:14:00 -05:00
return $_defer ;
}
2007-10-15 18:49:31 -04:00
/**
2008-06-22 16:23:23 -04:00
* Updates the amount of terms in taxonomy .
2008-02-05 01:47:27 -05:00
*
2008-06-22 16:23:23 -04:00
* If there is a taxonomy callback applyed , then it will be called for updating
* the count .
2007-10-15 18:49:31 -04:00
*
2008-06-22 16:23:23 -04:00
* The default action is to count what the amount of terms have the relationship
* of term ID . Once that is done , then update the database .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
2008-10-29 02:54:53 -04:00
* @ param int | array $terms The term_taxonomy_id of the terms
2007-10-15 18:49:31 -04:00
* @ param string $taxonomy The context of the term .
* @ return bool If no terms will return false , and if successful will return true .
*/
2007-12-12 00:14:00 -05:00
function wp_update_term_count ( $terms , $taxonomy , $do_deferred = false ) {
static $_deferred = array ();
if ( $do_deferred ) {
2008-08-06 16:31:54 -04:00
foreach ( ( array ) array_keys ( $_deferred ) as $tax ) {
2007-12-12 00:14:00 -05:00
wp_update_term_count_now ( $_deferred [ $tax ], $tax );
unset ( $_deferred [ $tax ] );
}
}
2007-09-15 13:35:32 -04:00
if ( empty ( $terms ) )
return false ;
if ( ! is_array ( $terms ) )
$terms = array ( $terms );
2007-12-12 00:14:00 -05:00
if ( wp_defer_term_counting () ) {
if ( ! isset ( $_deferred [ $taxonomy ]) )
$_deferred [ $taxonomy ] = array ();
$_deferred [ $taxonomy ] = array_unique ( array_merge ( $_deferred [ $taxonomy ], $terms ) );
return true ;
}
2008-02-05 01:47:27 -05:00
2007-12-12 00:14:00 -05:00
return wp_update_term_count_now ( $terms , $taxonomy );
}
2008-06-22 16:23:23 -04:00
/**
* Perform term count update immediately .
*
2008-08-30 17:23:43 -04:00
* @ since 2.5 . 0
2008-06-22 16:23:23 -04:00
*
2008-10-29 02:54:53 -04:00
* @ param array $terms The term_taxonomy_id of terms to update .
2008-06-22 16:23:23 -04:00
* @ param string $taxonomy The context of the term .
* @ return bool Always true when complete .
*/
2007-12-12 00:14:00 -05:00
function wp_update_term_count_now ( $terms , $taxonomy ) {
global $wpdb ;
2007-09-15 13:35:32 -04:00
$terms = array_map ( 'intval' , $terms );
$taxonomy = get_taxonomy ( $taxonomy );
if ( ! empty ( $taxonomy -> update_count_callback ) ) {
call_user_func ( $taxonomy -> update_count_callback , $terms );
} else {
// Default count updater
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $terms as $term ) {
2007-10-12 23:51:11 -04:00
$count = $wpdb -> get_var ( $wpdb -> prepare ( " SELECT COUNT(*) FROM $wpdb->term_relationships WHERE term_taxonomy_id = %d " , $term ) );
2007-10-13 14:23:59 -04:00
$wpdb -> update ( $wpdb -> term_taxonomy , compact ( 'count' ), array ( 'term_taxonomy_id' => $term ) );
2007-09-15 13:35:32 -04:00
}
}
clean_term_cache ( $terms );
return true ;
}
//
// Cache
//
2008-06-22 16:23:23 -04:00
2007-10-15 18:49:31 -04:00
/**
2008-06-22 16:23:23 -04:00
* Removes the taxonomy relationship to terms from the cache .
2007-10-21 13:18:24 -04:00
*
2008-06-22 16:23:23 -04:00
* 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 .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ see get_object_taxonomies () for more on $object_type
2007-12-13 19:25:39 -05:00
* @ uses do_action () Will call action hook named , 'clean_object_term_cache' after completion .
* Passes , function params in same order .
2007-10-15 18:49:31 -04:00
*
2007-12-13 19:25:39 -05:00
* @ param int | array $object_ids Single or list of term object ID ( s )
2008-03-24 18:43:20 -04:00
* @ param array | string $object_type The taxonomy object type
2007-10-15 18:49:31 -04:00
*/
2007-09-15 13:35:32 -04:00
function clean_object_term_cache ( $object_ids , $object_type ) {
if ( ! is_array ( $object_ids ) )
$object_ids = array ( $object_ids );
2007-10-13 14:23:59 -04:00
foreach ( $object_ids as $id )
2007-10-24 13:07:04 -04:00
foreach ( get_object_taxonomies ( $object_type ) as $taxonomy )
wp_cache_delete ( $id , " { $taxonomy } _relationships " );
2007-10-14 00:55:33 -04:00
do_action ( 'clean_object_term_cache' , $object_ids , $object_type );
2007-09-15 13:35:32 -04:00
}
2008-06-22 16:23:23 -04:00
2007-10-15 18:49:31 -04:00
/**
2008-06-22 16:23:23 -04:00
* Will remove all of the term ids from the cache .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
2007-12-13 19:25:39 -05:00
* @ param int | array $ids Single or list of Term IDs
2007-10-15 18:49:31 -04:00
* @ param string $taxonomy Can be empty and will assume tt_ids , else will use for context .
*/
2007-09-15 13:35:32 -04:00
function clean_term_cache ( $ids , $taxonomy = '' ) {
global $wpdb ;
2008-10-08 18:50:46 -04:00
static $cleaned = array ();
2007-09-15 13:35:32 -04:00
if ( ! is_array ( $ids ) )
$ids = array ( $ids );
$taxonomies = array ();
// If no taxonomy, assume tt_ids.
if ( empty ( $taxonomy ) ) {
$tt_ids = implode ( ', ' , $ids );
$terms = $wpdb -> get_results ( " SELECT term_id, taxonomy FROM $wpdb->term_taxonomy WHERE term_taxonomy_id IN ( $tt_ids ) " );
foreach ( ( array ) $terms as $term ) {
$taxonomies [] = $term -> taxonomy ;
wp_cache_delete ( $term -> term_id , $term -> taxonomy );
}
$taxonomies = array_unique ( $taxonomies );
} else {
foreach ( $ids as $id ) {
wp_cache_delete ( $id , $taxonomy );
}
$taxonomies = array ( $taxonomy );
}
foreach ( $taxonomies as $taxonomy ) {
2008-10-08 18:50:46 -04:00
if ( isset ( $cleaned [ $taxonomy ]) )
continue ;
$cleaned [ $taxonomy ] = true ;
2007-09-15 13:35:32 -04:00
wp_cache_delete ( 'all_ids' , $taxonomy );
wp_cache_delete ( 'get' , $taxonomy );
delete_option ( " { $taxonomy } _children " );
}
2008-10-08 18:50:46 -04:00
wp_cache_set ( 'last_changed' , time (), 'terms' );
2007-10-14 00:55:33 -04:00
do_action ( 'clean_term_cache' , $ids , $taxonomy );
2007-09-15 13:35:32 -04:00
}
2008-06-22 16:23:23 -04:00
2007-10-21 13:18:24 -04:00
/**
2008-06-22 16:23:23 -04:00
* Retrieves the taxonomy relationship to the term object id .
2007-10-21 13:18:24 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
2007-12-13 19:25:39 -05:00
* @ uses wp_cache_get () Retrieves taxonomy relationship from cache
*
* @ param int | array $id Term object ID
* @ param string $taxonomy Taxonomy Name
2007-10-21 13:18:24 -04:00
* @ return bool | array Empty array if $terms found , but not $taxonomy . False if nothing is in cache for $taxonomy and $id .
*/
2007-09-15 13:35:32 -04:00
function & get_object_term_cache ( $id , $taxonomy ) {
2008-01-10 15:51:07 -05:00
$cache = wp_cache_get ( $id , " { $taxonomy } _relationships " );
return $cache ;
2007-09-15 13:35:32 -04:00
}
2008-06-22 16:23:23 -04:00
2007-10-21 13:18:24 -04:00
/**
2008-06-22 16:23:23 -04:00
* Updates the cache for Term ID ( s ) .
2007-12-13 19:25:39 -05:00
*
* Will only update the cache for terms not already cached .
*
2008-06-22 16:23:23 -04:00
* The $object_ids expects that the ids be separated by commas , if it is a
* string .
2007-10-21 13:18:24 -04:00
*
2008-06-22 16:23:23 -04:00
* It should be noted that update_object_term_cache () is very time extensive . It
* is advised that the function is not called very often or at least not for a
* lot of terms that exist in a lot of taxonomies . The amount of time increases
* for each term and it also increases for each taxonomy the term belongs to .
2007-10-21 13:18:24 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-12-13 19:25:39 -05:00
* @ uses wp_get_object_terms () Used to get terms from the database to update
2007-10-21 13:18:24 -04:00
*
2007-12-13 19:25:39 -05:00
* @ param string | array $object_ids Single or list of term object ID ( s )
2008-03-24 18:43:20 -04:00
* @ param array | string $object_type The taxonomy object type
2008-02-05 01:47:27 -05:00
* @ return null | bool Null value is given with empty $object_ids . False if
2007-10-21 13:18:24 -04:00
*/
2007-09-15 13:35:32 -04:00
function update_object_term_cache ( $object_ids , $object_type ) {
if ( empty ( $object_ids ) )
return ;
if ( ! is_array ( $object_ids ) )
$object_ids = explode ( ',' , $object_ids );
2007-10-13 14:23:59 -04:00
$object_ids = array_map ( 'intval' , $object_ids );
2007-09-15 13:35:32 -04:00
2007-10-23 16:33:50 -04:00
$taxonomies = get_object_taxonomies ( $object_type );
2007-10-13 14:23:59 -04:00
$ids = array ();
foreach ( ( array ) $object_ids as $id ) {
2007-10-23 16:33:50 -04:00
foreach ( $taxonomies as $taxonomy ) {
if ( false === wp_cache_get ( $id , " { $taxonomy } _relationships " ) ) {
$ids [] = $id ;
break ;
}
}
2007-10-13 14:23:59 -04:00
}
2007-09-15 13:35:32 -04:00
2007-10-13 14:23:59 -04:00
if ( empty ( $ids ) )
return false ;
2007-09-15 13:35:32 -04:00
2007-10-23 16:33:50 -04:00
$terms = wp_get_object_terms ( $ids , $taxonomies , 'fields=all_with_object_id' );
2007-09-15 13:35:32 -04:00
2007-10-13 14:23:59 -04:00
$object_terms = array ();
foreach ( ( array ) $terms as $term )
$object_terms [ $term -> object_id ][ $term -> taxonomy ][ $term -> term_id ] = $term ;
2007-09-15 13:35:32 -04:00
2007-10-13 14:23:59 -04:00
foreach ( $ids as $id ) {
2007-10-23 16:33:50 -04:00
foreach ( $taxonomies as $taxonomy ) {
if ( ! isset ( $object_terms [ $id ][ $taxonomy ]) ) {
if ( ! isset ( $object_terms [ $id ]) )
$object_terms [ $id ] = array ();
$object_terms [ $id ][ $taxonomy ] = array ();
}
}
2007-09-15 13:35:32 -04:00
}
2007-10-13 14:23:59 -04:00
2007-10-23 16:33:50 -04:00
foreach ( $object_terms as $id => $value ) {
foreach ( $value as $taxonomy => $terms ) {
wp_cache_set ( $id , $terms , " { $taxonomy } _relationships " );
}
}
2007-09-15 13:35:32 -04:00
}
2008-06-22 16:23:23 -04:00
2007-10-21 13:18:24 -04:00
/**
2008-06-22 16:23:23 -04:00
* Updates Terms to Taxonomy in cache .
2007-10-21 13:18:24 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
* @ param array $terms List of Term objects to change
* @ param string $taxonomy Optional . Update Term to this taxonomy in cache
*/
2007-09-15 13:35:32 -04:00
function update_term_cache ( $terms , $taxonomy = '' ) {
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $terms as $term ) {
2007-09-15 13:35:32 -04:00
$term_taxonomy = $taxonomy ;
if ( empty ( $term_taxonomy ) )
$term_taxonomy = $term -> taxonomy ;
wp_cache_add ( $term -> term_id , $term , $term_taxonomy );
}
}
//
// Private
//
2008-06-22 16:23:23 -04:00
2007-10-21 13:18:24 -04:00
/**
2008-06-22 16:23:23 -04:00
* Retrieves children of taxonomy .
2007-10-21 13:18:24 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
* @ access private
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
*
2008-06-22 16:23:23 -04:00
* @ uses update_option () Stores all of the children in " $taxonomy_children "
* option . That is the name of the taxonomy , immediately followed by '_children' .
2007-12-13 19:25:39 -05:00
*
* @ param string $taxonomy Taxonomy Name
2007-10-21 13:18:24 -04:00
* @ return array Empty if $taxonomy isn ' t hierarachical or returns children .
*/
2007-09-15 13:35:32 -04:00
function _get_term_hierarchy ( $taxonomy ) {
if ( ! is_taxonomy_hierarchical ( $taxonomy ) )
return array ();
$children = get_option ( " { $taxonomy } _children " );
if ( is_array ( $children ) )
return $children ;
$children = array ();
$terms = get_terms ( $taxonomy , 'get=all' );
foreach ( $terms as $term ) {
if ( $term -> parent > 0 )
$children [ $term -> parent ][] = $term -> term_id ;
}
update_option ( " { $taxonomy } _children " , $children );
return $children ;
}
2008-06-22 16:23:23 -04:00
2007-10-15 18:49:31 -04:00
/**
2008-11-12 19:20:12 -05:00
* Get the subset of $terms that are descendants of $term_id .
2008-02-05 01:47:27 -05:00
*
2008-11-12 19:20:12 -05:00
* 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 .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2007-10-21 13:18:24 -04:00
* @ access private
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-15 18:49:31 -04:00
*
2008-11-12 19:20:12 -05:00
* @ 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 .
2008-12-09 13:03:31 -05:00
* @ return array The subset of $terms that are descendants of $term_id .
2007-10-15 18:49:31 -04:00
*/
2007-09-15 13:35:32 -04:00
function & _get_term_children ( $term_id , $terms , $taxonomy ) {
2008-01-10 15:51:07 -05:00
$empty_array = array ();
2007-09-15 13:35:32 -04:00
if ( empty ( $terms ) )
2008-01-10 15:51:07 -05:00
return $empty_array ;
2007-09-15 13:35:32 -04:00
$term_list = array ();
$has_children = _get_term_hierarchy ( $taxonomy );
if ( ( 0 != $term_id ) && ! isset ( $has_children [ $term_id ]) )
2008-01-10 15:51:07 -05:00
return $empty_array ;
2007-09-15 13:35:32 -04:00
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $terms as $term ) {
2007-09-15 13:35:32 -04:00
$use_id = false ;
if ( ! is_object ( $term ) ) {
$term = get_term ( $term , $taxonomy );
2007-09-18 12:32:22 -04:00
if ( is_wp_error ( $term ) )
return $term ;
2007-09-15 13:35:32 -04:00
$use_id = true ;
}
if ( $term -> term_id == $term_id )
continue ;
if ( $term -> parent == $term_id ) {
if ( $use_id )
$term_list [] = $term -> term_id ;
else
$term_list [] = $term ;
if ( ! isset ( $has_children [ $term -> term_id ]) )
continue ;
if ( $children = _get_term_children ( $term -> term_id , $terms , $taxonomy ) )
$term_list = array_merge ( $term_list , $children );
}
}
return $term_list ;
}
2008-06-22 16:23:23 -04:00
2007-10-15 18:49:31 -04:00
/**
2008-06-22 16:23:23 -04:00
* Add count of children to parent count .
2008-02-05 01:47:27 -05:00
*
2008-06-22 16:23:23 -04:00
* Recalculates term counts by including items from child terms . Assumes all
* relevant children are already in the $terms argument .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2007-10-21 13:18:24 -04:00
* @ access private
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
* @ param array $terms List of Term IDs
* @ param string $taxonomy Term Context
2007-10-21 13:18:24 -04:00
* @ return null Will break from function if conditions are not met .
2007-10-15 18:49:31 -04:00
*/
2007-09-15 13:35:32 -04:00
function _pad_term_counts ( & $terms , $taxonomy ) {
2007-09-22 20:35:59 -04:00
global $wpdb ;
// This function only works for post categories.
if ( 'category' != $taxonomy )
return ;
2007-09-15 13:35:32 -04:00
$term_hier = _get_term_hierarchy ( $taxonomy );
if ( empty ( $term_hier ) )
return ;
2007-09-22 20:35:59 -04:00
$term_items = array ();
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $terms as $key => $term ) {
2007-09-22 20:35:59 -04:00
$terms_by_id [ $term -> term_id ] = & $terms [ $key ];
$term_ids [ $term -> term_taxonomy_id ] = $term -> term_id ;
}
// Get the object and term ids and stick them in a lookup table
2007-10-11 13:43:49 -04:00
$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 ( " . join ( ',' , array_keys ( $term_ids )) . " ) AND post_type = 'post' AND post_status = 'publish' " );
2007-09-22 20:35:59 -04:00
foreach ( $results as $row ) {
$id = $term_ids [ $row -> term_taxonomy_id ];
2008-11-10 18:03:34 -05:00
$term_items [ $id ][ $row -> object_id ] = isset ( $term_items [ $id ][ $row -> object_id ]) ? ++ $term_items [ $id ][ $row -> object_id ] : 1 ;
2007-09-22 20:35:59 -04:00
}
2008-12-09 13:03:31 -05:00
2007-09-22 20:35:59 -04:00
// Touch every ancestor's lookup row for each post in each term
foreach ( $term_ids as $term_id ) {
$child = $term_id ;
while ( $parent = $terms_by_id [ $child ] -> parent ) {
if ( ! empty ( $term_items [ $term_id ]) )
2008-11-10 18:03:34 -05:00
foreach ( $term_items [ $term_id ] as $item_id => $touches ) {
$term_items [ $parent ][ $item_id ] = isset ( $term_items [ $parent ][ $item_id ]) ? ++ $term_items [ $parent ][ $item_id ] : 1 ;
}
2007-09-22 20:35:59 -04:00
$child = $parent ;
2007-09-15 13:35:32 -04:00
}
}
2007-09-22 20:35:59 -04:00
2008-02-05 01:47:27 -05:00
// Transfer the touched cells
2007-09-22 20:35:59 -04:00
foreach ( ( array ) $term_items as $id => $items )
if ( isset ( $terms_by_id [ $id ]) )
$terms_by_id [ $id ] -> count = count ( $items );
2007-09-15 13:35:32 -04:00
}
//
// Default callbacks
//
2007-10-15 18:49:31 -04:00
/**
2008-06-22 16:23:23 -04:00
* Will update term count based on posts .
2008-02-05 01:47:27 -05:00
*
2008-06-22 16:23:23 -04:00
* Private function for the default callback for post_tag and category
* taxonomies .
2007-10-15 18:49:31 -04:00
*
* @ package WordPress
* @ subpackage Taxonomy
2007-10-21 13:18:24 -04:00
* @ access private
2008-08-30 17:23:43 -04:00
* @ since 2.3 . 0
2007-10-21 13:18:24 -04:00
* @ uses $wpdb
2007-10-15 18:49:31 -04:00
*
2008-10-29 02:54:53 -04:00
* @ param array $terms List of Term taxonomy IDs
2007-10-15 18:49:31 -04:00
*/
2007-09-15 13:35:32 -04:00
function _update_post_term_count ( $terms ) {
global $wpdb ;
2008-08-06 16:31:54 -04:00
foreach ( ( array ) $terms as $term ) {
2007-10-12 23:51:11 -04:00
$count = $wpdb -> get_var ( $wpdb -> prepare ( " SELECT COUNT(*) FROM $wpdb->term_relationships , $wpdb->posts WHERE $wpdb->posts .ID = $wpdb->term_relationships .object_id AND post_status = 'publish' AND post_type = 'post' AND term_taxonomy_id = %d " , $term ) );
2007-10-13 14:23:59 -04:00
$wpdb -> update ( $wpdb -> term_taxonomy , compact ( 'count' ), array ( 'term_taxonomy_id' => $term ) );
2007-09-15 13:35:32 -04:00
}
}
2008-06-22 16:23:23 -04:00
2008-03-26 02:37:19 -04:00
/**
2008-06-22 16:23:23 -04:00
* Generates a permalink for a taxonomy term archive .
*
2008-08-30 17:23:43 -04:00
* @ since 2.5 . 0
2008-03-26 02:37:19 -04:00
*
* @ param object | int | string $term
* @ param string $taxonomy
* @ return string HTML link to taxonomy term archive
*/
function get_term_link ( $term , $taxonomy ) {
global $wp_rewrite ;
2008-03-26 14:26:22 -04:00
// use legacy functions for core taxonomies until they are fully plugged in
if ( $taxonomy == 'category' )
return get_category_link ( $term );
if ( $taxonomy == 'post_tag' )
return get_tag_link ( $term );
2008-03-26 02:37:19 -04:00
$termlink = $wp_rewrite -> get_extra_permastruct ( $taxonomy );
if ( ! is_object ( $term ) ) {
if ( is_int ( $term ) ) {
$term = & get_term ( $term , $taxonomy );
} else {
$term = & get_term_by ( 'slug' , $term , $taxonomy );
}
}
if ( is_wp_error ( $term ) )
return $term ;
$slug = $term -> slug ;
if ( empty ( $termlink ) ) {
$file = get_option ( 'home' ) . '/' ;
$t = get_taxonomy ( $taxonomy );
if ( $t -> query_var )
$termlink = " $file ? $t->query_var = $slug " ;
else
$termlink = " $file ?taxonomy= $taxonomy &term= $slug " ;
} else {
$termlink = str_replace ( " % $taxonomy % " , $slug , $termlink );
$termlink = get_option ( 'home' ) . user_trailingslashit ( $termlink , 'category' );
}
return apply_filters ( 'term_link' , $termlink , $term , $taxonomy );
}
2008-06-22 16:23:23 -04:00
/**
* Display the taxonomies of a post with available options .
*
* This function can be used within the loop to display the taxonomies for a
* post without specifying the Post ID . You can also use it outside the Loop to
* display the taxonomies for a specific post .
*
* The available defaults are :
* 'post' : default is 0. The post ID to get taxonomies of .
* 'before' : default is empty string . Display before taxonomies list .
* 'sep' : default is empty string . Separate every taxonomy with value in this .
* 'after' : default is empty string . Display this after the taxonomies list .
*
2008-08-30 17:23:43 -04:00
* @ since 2.5 . 0
2008-06-22 16:23:23 -04:00
* @ uses get_the_taxonomies ()
*
* @ param array $args Override the defaults .
*/
2008-03-26 02:37:19 -04:00
function the_taxonomies ( $args = array ()) {
$defaults = array (
'post' => 0 ,
'before' => '' ,
'sep' => ' ' ,
'after' => '' ,
);
$r = wp_parse_args ( $args , $defaults );
extract ( $r , EXTR_SKIP );
echo $before . join ( $sep , get_the_taxonomies ( $post )) . $after ;
}
2008-06-22 16:23:23 -04:00
/**
* Retrieve all taxonomies associated with a post .
*
* This function can be used within the loop . It will also return an array of
* the taxonomies with links to the taxonomy and name .
*
2008-08-30 17:23:43 -04:00
* @ since 2.5 . 0
2008-06-22 16:23:23 -04:00
*
* @ param int $post Optional . Post ID or will use Global Post ID ( in loop ) .
* @ return array
*/
2008-03-26 02:37:19 -04:00
function get_the_taxonomies ( $post = 0 ) {
if ( is_int ( $post ) )
$post =& get_post ( $post );
elseif ( ! is_object ( $post ) )
$post =& $GLOBALS [ 'post' ];
$taxonomies = array ();
if ( ! $post )
return $taxonomies ;
2008-03-26 14:26:22 -04:00
$template = apply_filters ( 'taxonomy_template' , '%s: %l.' );
2008-03-26 02:37:19 -04:00
foreach ( get_object_taxonomies ( $post ) as $taxonomy ) {
$t = ( array ) get_taxonomy ( $taxonomy );
if ( empty ( $t [ 'label' ]) )
$t [ 'label' ] = $taxonomy ;
if ( empty ( $t [ 'args' ]) )
$t [ 'args' ] = array ();
if ( empty ( $t [ 'template' ]) )
2008-03-26 14:26:22 -04:00
$t [ 'template' ] = $template ;
2008-03-26 02:37:19 -04:00
$terms = get_object_term_cache ( $post -> ID , $taxonomy );
if ( empty ( $terms ) )
$terms = wp_get_object_terms ( $post -> ID , $taxonomy , $t [ 'args' ]);
$links = array ();
foreach ( $terms as $term )
$links [] = " <a href=' " . attribute_escape ( get_term_link ( $term , $taxonomy )) . " '> $term->name </a> " ;
if ( $links )
$taxonomies [ $taxonomy ] = wp_sprintf ( $t [ 'template' ], $t [ 'label' ], $links , $terms );
}
return $taxonomies ;
}
2008-06-22 16:23:23 -04:00
/**
* Retrieve all taxonomies of a post with just the names .
*
2008-08-30 17:23:43 -04:00
* @ since 2.5 . 0
2008-06-22 16:23:23 -04:00
* @ uses get_object_taxonomies ()
*
* @ param int $post Optional . Post ID
* @ return array
*/
2008-03-26 02:37:19 -04:00
function get_post_taxonomies ( $post = 0 ) {
$post =& get_post ( $post );
return get_object_taxonomies ( $post );
}
2008-12-09 18:31:11 -05:00
/**
* Determine if the given object is associated with any of the given terms .
*
* The given terms are checked against the object 's terms' term_ids , names and slugs .
* Terms given as integers will only be checked against the object 's terms' term_ids .
* If no terms are given , determines if object is associated with any terms in the given taxonomy .
*
* @ since 2.7 . 0
* @ uses get_object_term_cache ()
* @ uses wp_get_object_terms ()
*
* @ 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
* @ return bool | WP_Error . WP_Error on input error .
*/
function is_object_in_term ( $object_id , $taxonomy , $terms = null ) {
if ( ! $object_id = ( int ) $object_id )
return new WP_Error ( 'invalid_object' , __ ( 'Invalid object ID' ) );
$object_terms = get_object_term_cache ( $object_id , $taxonomy );
if ( empty ( $object_terms ) )
$object_terms = wp_get_object_terms ( $object_id , $taxonomy );
if ( is_wp_error ( $object_terms ) )
return $object_terms ;
if ( empty ( $object_terms ) )
return false ;
if ( empty ( $terms ) )
return ( ! empty ( $object_terms ) );
$terms = ( array ) $terms ;
if ( $ints = array_filter ( $terms , 'is_int' ) )
$strs = array_diff ( $terms , $ints );
else
$strs =& $terms ;
foreach ( $object_terms as $object_term ) {
if ( $ints && in_array ( $object_term -> term_id , $ints ) ) return true ; // If int, check against term_id
if ( $strs ) {
if ( in_array ( $object_term -> term_id , $strs ) ) return true ;
if ( in_array ( $object_term -> name , $strs ) ) return true ;
if ( in_array ( $object_term -> slug , $strs ) ) return true ;
}
}
return false ;
}
2008-08-06 16:31:54 -04:00
?>