wp/wp-includes/category.php
changeset 0 d970ebf37754
child 5 5e2f62d02dcd
equal deleted inserted replaced
-1:000000000000 0:d970ebf37754
       
     1 <?php
       
     2 /**
       
     3  * WordPress Category API
       
     4  *
       
     5  * @package WordPress
       
     6  */
       
     7 
       
     8 /**
       
     9  * Retrieves all category IDs.
       
    10  *
       
    11  * @since 2.0.0
       
    12  * @link http://codex.wordpress.org/Function_Reference/get_all_category_ids
       
    13  *
       
    14  * @return object List of all of the category IDs.
       
    15  */
       
    16 function get_all_category_ids() {
       
    17 	if ( ! $cat_ids = wp_cache_get( 'all_category_ids', 'category' ) ) {
       
    18 		$cat_ids = get_terms( 'category', array('fields' => 'ids', 'get' => 'all') );
       
    19 		wp_cache_add( 'all_category_ids', $cat_ids, 'category' );
       
    20 	}
       
    21 
       
    22 	return $cat_ids;
       
    23 }
       
    24 
       
    25 /**
       
    26  * Retrieve list of category objects.
       
    27  *
       
    28  * If you change the type to 'link' in the arguments, then the link categories
       
    29  * will be returned instead. Also all categories will be updated to be backwards
       
    30  * compatible with pre-2.3 plugins and themes.
       
    31  *
       
    32  * @since 2.1.0
       
    33  * @see get_terms() Type of arguments that can be changed.
       
    34  * @link http://codex.wordpress.org/Function_Reference/get_categories
       
    35  *
       
    36  * @param string|array $args Optional. Change the defaults retrieving categories.
       
    37  * @return array List of categories.
       
    38  */
       
    39 function get_categories( $args = '' ) {
       
    40 	$defaults = array( 'taxonomy' => 'category' );
       
    41 	$args = wp_parse_args( $args, $defaults );
       
    42 
       
    43 	$taxonomy = $args['taxonomy'];
       
    44 	/**
       
    45 	 * Filter the taxonomy used to retrieve terms when calling get_categories().
       
    46 	 *
       
    47 	 * @since 2.7.0
       
    48 	 *
       
    49 	 * @param string $taxonomy Taxonomy to retrieve terms from.
       
    50 	 * @param array  $args     An array of arguments. @see get_terms()
       
    51 	 */
       
    52 	$taxonomy = apply_filters( 'get_categories_taxonomy', $taxonomy, $args );
       
    53 
       
    54 	// Back compat
       
    55 	if ( isset($args['type']) && 'link' == $args['type'] ) {
       
    56 		_deprecated_argument( __FUNCTION__, '3.0', '' );
       
    57 		$taxonomy = $args['taxonomy'] = 'link_category';
       
    58 	}
       
    59 
       
    60 	$categories = (array) get_terms( $taxonomy, $args );
       
    61 
       
    62 	foreach ( array_keys( $categories ) as $k )
       
    63 		_make_cat_compat( $categories[$k] );
       
    64 
       
    65 	return $categories;
       
    66 }
       
    67 
       
    68 /**
       
    69  * Retrieves category data given a category ID or category object.
       
    70  *
       
    71  * If you pass the $category parameter an object, which is assumed to be the
       
    72  * category row object retrieved the database. It will cache the category data.
       
    73  *
       
    74  * If you pass $category an integer of the category ID, then that category will
       
    75  * be retrieved from the database, if it isn't already cached, and pass it back.
       
    76  *
       
    77  * If you look at get_term(), then both types will be passed through several
       
    78  * filters and finally sanitized based on the $filter parameter value.
       
    79  *
       
    80  * The category will converted to maintain backwards compatibility.
       
    81  *
       
    82  * @since 1.5.1
       
    83  * @uses get_term() Used to get the category data from the taxonomy.
       
    84  *
       
    85  * @param int|object $category Category ID or Category row object
       
    86  * @param string $output Optional. Constant OBJECT, ARRAY_A, or ARRAY_N
       
    87  * @param string $filter Optional. Default is raw or no WordPress defined filter will applied.
       
    88  * @return mixed Category data in type defined by $output parameter.
       
    89  */
       
    90 function get_category( $category, $output = OBJECT, $filter = 'raw' ) {
       
    91 	$category = get_term( $category, 'category', $output, $filter );
       
    92 	if ( is_wp_error( $category ) )
       
    93 		return $category;
       
    94 
       
    95 	_make_cat_compat( $category );
       
    96 
       
    97 	return $category;
       
    98 }
       
    99 
       
   100 /**
       
   101  * Retrieve category based on URL containing the category slug.
       
   102  *
       
   103  * Breaks the $category_path parameter up to get the category slug.
       
   104  *
       
   105  * Tries to find the child path and will return it. If it doesn't find a
       
   106  * match, then it will return the first category matching slug, if $full_match,
       
   107  * is set to false. If it does not, then it will return null.
       
   108  *
       
   109  * It is also possible that it will return a WP_Error object on failure. Check
       
   110  * for it when using this function.
       
   111  *
       
   112  * @since 2.1.0
       
   113  *
       
   114  * @param string $category_path URL containing category slugs.
       
   115  * @param bool $full_match Optional. Whether full path should be matched.
       
   116  * @param string $output Optional. Constant OBJECT, ARRAY_A, or ARRAY_N
       
   117  * @return null|object|array Null on failure. Type is based on $output value.
       
   118  */
       
   119 function get_category_by_path( $category_path, $full_match = true, $output = OBJECT ) {
       
   120 	$category_path = rawurlencode( urldecode( $category_path ) );
       
   121 	$category_path = str_replace( '%2F', '/', $category_path );
       
   122 	$category_path = str_replace( '%20', ' ', $category_path );
       
   123 	$category_paths = '/' . trim( $category_path, '/' );
       
   124 	$leaf_path  = sanitize_title( basename( $category_paths ) );
       
   125 	$category_paths = explode( '/', $category_paths );
       
   126 	$full_path = '';
       
   127 	foreach ( (array) $category_paths as $pathdir )
       
   128 		$full_path .= ( $pathdir != '' ? '/' : '' ) . sanitize_title( $pathdir );
       
   129 
       
   130 	$categories = get_terms( 'category', array('get' => 'all', 'slug' => $leaf_path) );
       
   131 
       
   132 	if ( empty( $categories ) )
       
   133 		return null;
       
   134 
       
   135 	foreach ( $categories as $category ) {
       
   136 		$path = '/' . $leaf_path;
       
   137 		$curcategory = $category;
       
   138 		while ( ( $curcategory->parent != 0 ) && ( $curcategory->parent != $curcategory->term_id ) ) {
       
   139 			$curcategory = get_term( $curcategory->parent, 'category' );
       
   140 			if ( is_wp_error( $curcategory ) )
       
   141 				return $curcategory;
       
   142 			$path = '/' . $curcategory->slug . $path;
       
   143 		}
       
   144 
       
   145 		if ( $path == $full_path ) {
       
   146 			$category = get_term( $category->term_id, 'category', $output );
       
   147 			_make_cat_compat( $category );
       
   148 			return $category;
       
   149 		}
       
   150 	}
       
   151 
       
   152 	// If full matching is not required, return the first cat that matches the leaf.
       
   153 	if ( ! $full_match ) {
       
   154 		$category = get_term( reset( $categories )->term_id, 'category', $output );
       
   155 		_make_cat_compat( $category );
       
   156 		return $category;
       
   157 	}
       
   158 
       
   159 	return null;
       
   160 }
       
   161 
       
   162 /**
       
   163  * Retrieve category object by category slug.
       
   164  *
       
   165  * @since 2.3.0
       
   166  *
       
   167  * @param string $slug The category slug.
       
   168  * @return object Category data object
       
   169  */
       
   170 function get_category_by_slug( $slug  ) {
       
   171 	$category = get_term_by( 'slug', $slug, 'category' );
       
   172 	if ( $category )
       
   173 		_make_cat_compat( $category );
       
   174 
       
   175 	return $category;
       
   176 }
       
   177 
       
   178 /**
       
   179  * Retrieve the ID of a category from its name.
       
   180  *
       
   181  * @since 1.0.0
       
   182  *
       
   183  * @param string $cat_name Category name.
       
   184  * @return int 0, if failure and ID of category on success.
       
   185  */
       
   186 function get_cat_ID( $cat_name ) {
       
   187 	$cat = get_term_by( 'name', $cat_name, 'category' );
       
   188 	if ( $cat )
       
   189 		return $cat->term_id;
       
   190 	return 0;
       
   191 }
       
   192 
       
   193 /**
       
   194  * Retrieve the name of a category from its ID.
       
   195  *
       
   196  * @since 1.0.0
       
   197  *
       
   198  * @param int $cat_id Category ID
       
   199  * @return string Category name, or an empty string if category doesn't exist.
       
   200  */
       
   201 function get_cat_name( $cat_id ) {
       
   202 	$cat_id = (int) $cat_id;
       
   203 	$category = get_term( $cat_id, 'category' );
       
   204 	if ( ! $category || is_wp_error( $category ) )
       
   205 		return '';
       
   206 	return $category->name;
       
   207 }
       
   208 
       
   209 /**
       
   210  * Check if a category is an ancestor of another category.
       
   211  *
       
   212  * You can use either an id or the category object for both parameters. If you
       
   213  * use an integer the category will be retrieved.
       
   214  *
       
   215  * @since 2.1.0
       
   216  *
       
   217  * @param int|object $cat1 ID or object to check if this is the parent category.
       
   218  * @param int|object $cat2 The child category.
       
   219  * @return bool Whether $cat2 is child of $cat1
       
   220  */
       
   221 function cat_is_ancestor_of( $cat1, $cat2 ) {
       
   222 	return term_is_ancestor_of( $cat1, $cat2, 'category' );
       
   223 }
       
   224 
       
   225 /**
       
   226  * Sanitizes category data based on context.
       
   227  *
       
   228  * @since 2.3.0
       
   229  * @uses sanitize_term() See this function for what context are supported.
       
   230  *
       
   231  * @param object|array $category Category data
       
   232  * @param string $context Optional. Default is 'display'.
       
   233  * @return object|array Same type as $category with sanitized data for safe use.
       
   234  */
       
   235 function sanitize_category( $category, $context = 'display' ) {
       
   236 	return sanitize_term( $category, 'category', $context );
       
   237 }
       
   238 
       
   239 /**
       
   240  * Sanitizes data in single category key field.
       
   241  *
       
   242  * @since 2.3.0
       
   243  * @uses sanitize_term_field() See function for more details.
       
   244  *
       
   245  * @param string $field Category key to sanitize
       
   246  * @param mixed $value Category value to sanitize
       
   247  * @param int $cat_id Category ID
       
   248  * @param string $context What filter to use, 'raw', 'display', etc.
       
   249  * @return mixed Same type as $value after $value has been sanitized.
       
   250  */
       
   251 function sanitize_category_field( $field, $value, $cat_id, $context ) {
       
   252 	return sanitize_term_field( $field, $value, $cat_id, 'category', $context );
       
   253 }
       
   254 
       
   255 /* Tags */
       
   256 
       
   257 /**
       
   258  * Retrieves all post tags.
       
   259  *
       
   260  * @since 2.3.0
       
   261  * @see get_terms() For list of arguments to pass.
       
   262  * @uses apply_filters() Calls 'get_tags' hook on array of tags and with $args.
       
   263  *
       
   264  * @param string|array $args Tag arguments to use when retrieving tags.
       
   265  * @return array List of tags.
       
   266  */
       
   267 function get_tags( $args = '' ) {
       
   268 	$tags = get_terms( 'post_tag', $args );
       
   269 
       
   270 	if ( empty( $tags ) ) {
       
   271 		$return = array();
       
   272 		return $return;
       
   273 	}
       
   274 
       
   275 	/**
       
   276 	 * Filter the array of term objects returned for the 'post_tag' taxonomy.
       
   277 	 *
       
   278 	 * @since 2.3.0
       
   279 	 *
       
   280 	 * @param array $tags Array of 'post_tag' term objects.
       
   281 	 * @param array $args An array of arguments. @see get_terms()
       
   282 	 */
       
   283 	$tags = apply_filters( 'get_tags', $tags, $args );
       
   284 	return $tags;
       
   285 }
       
   286 
       
   287 /**
       
   288  * Retrieve post tag by tag ID or tag object.
       
   289  *
       
   290  * If you pass the $tag parameter an object, which is assumed to be the tag row
       
   291  * object retrieved the database. It will cache the tag data.
       
   292  *
       
   293  * If you pass $tag an integer of the tag ID, then that tag will
       
   294  * be retrieved from the database, if it isn't already cached, and pass it back.
       
   295  *
       
   296  * If you look at get_term(), then both types will be passed through several
       
   297  * filters and finally sanitized based on the $filter parameter value.
       
   298  *
       
   299  * @since 2.3.0
       
   300  *
       
   301  * @param int|object $tag
       
   302  * @param string $output Optional. Constant OBJECT, ARRAY_A, or ARRAY_N
       
   303  * @param string $filter Optional. Default is raw or no WordPress defined filter will applied.
       
   304  * @return object|array Return type based on $output value.
       
   305  */
       
   306 function get_tag( $tag, $output = OBJECT, $filter = 'raw' ) {
       
   307 	return get_term( $tag, 'post_tag', $output, $filter );
       
   308 }
       
   309 
       
   310 /* Cache */
       
   311 
       
   312 /**
       
   313  * Remove the category cache data based on ID.
       
   314  *
       
   315  * @since 2.1.0
       
   316  * @uses clean_term_cache() Clears the cache for the category based on ID
       
   317  *
       
   318  * @param int $id Category ID
       
   319  */
       
   320 function clean_category_cache( $id ) {
       
   321 	clean_term_cache( $id, 'category' );
       
   322 }
       
   323 
       
   324 /**
       
   325  * Update category structure to old pre 2.3 from new taxonomy structure.
       
   326  *
       
   327  * This function was added for the taxonomy support to update the new category
       
   328  * structure with the old category one. This will maintain compatibility with
       
   329  * plugins and themes which depend on the old key or property names.
       
   330  *
       
   331  * The parameter should only be passed a variable and not create the array or
       
   332  * object inline to the parameter. The reason for this is that parameter is
       
   333  * passed by reference and PHP will fail unless it has the variable.
       
   334  *
       
   335  * There is no return value, because everything is updated on the variable you
       
   336  * pass to it. This is one of the features with using pass by reference in PHP.
       
   337  *
       
   338  * @since 2.3.0
       
   339  * @access private
       
   340  *
       
   341  * @param array|object $category Category Row object or array
       
   342  */
       
   343 function _make_cat_compat( &$category ) {
       
   344 	if ( is_object( $category ) ) {
       
   345 		$category->cat_ID = &$category->term_id;
       
   346 		$category->category_count = &$category->count;
       
   347 		$category->category_description = &$category->description;
       
   348 		$category->cat_name = &$category->name;
       
   349 		$category->category_nicename = &$category->slug;
       
   350 		$category->category_parent = &$category->parent;
       
   351 	} elseif ( is_array( $category ) && isset( $category['term_id'] ) ) {
       
   352 		$category['cat_ID'] = &$category['term_id'];
       
   353 		$category['category_count'] = &$category['count'];
       
   354 		$category['category_description'] = &$category['description'];
       
   355 		$category['cat_name'] = &$category['name'];
       
   356 		$category['category_nicename'] = &$category['slug'];
       
   357 		$category['category_parent'] = &$category['parent'];
       
   358 	}
       
   359 }