wp_get_post_categories() │ WP 2.1.0

Gets the list of post categories as an array.

This function is a wrapper for wp_get_object_terms() and is designed for abstraction away from the complexity of "WordPress taxonomy" concept.

The result of this function is not cached, so a query to the database is made every time the function is called. Use this function with caution. For better performance, you should use functions like get_the_category() whose results are cached.

Uses: wp_get_object_terms()
1 time — 0.00111 sec (very slow) | 50000 times — 43.9 sec (very slow)

No Hooks.

Returns

Array|WP_Error. List of categories. If the $fields argument passed via $args is:

  • all or all_with_object_id - an array of WP_Term objects will be returned.
  • ids - an array of category IDs.
  • names - an array of category names.
  • WP_Error object if 'category' taxonomy doesn't exist.

Usage

wp_get_post_categories( $post_id, $args );
$post_id(int)
The Post ID. Does not default to the ID of the global $post.
Default: 0
$args(array)
Category query parameters.
Default: array()

$args Arguments

See WP_Term_Query::__construct() for all supported arguments.

orderby(string)

By which criterion to sort the result. Could be:

  • count - by number of posts;
  • name - by name. (default);
  • slug - by slug;
  • none - output without sorting.

Default: 'name'

order(string)
Sort direction. ASC - in order, DESC - in reverse order.
Default: 'ASC'
fields(string)

Which fields to include in the resulting array. Could be:

  • all - an array of WP_Term objects with all the information about each category;
  • all_with_object_id - the same as all, plus term IDs;
  • ids - get term IDs only;
  • names - get term names only.

Default: 'ids'

Examples

0

#1 Demonstration of the function

This example shows the result of a basic use of this function:

$test = wp_get_post_categories( $post->ID );

print_r( $test );

/* Displays:
Array
(
	[0] => 1
	[1] => 2
)
*/

echo $test[1]; // Displays: 2
0

#2 Let's collect the categories information

The example below shows how to get the post categories and then collect the required data into the $cats array.

$post_categories = wp_get_post_categories( $post_id );

$cats = array();

foreach( $post_categories as $c ){

	$cat = get_category( $c );

	$cats[] = [ 'name' => $cat->name, 'slug' => $cat->slug ];
}
-1

#3 Get all the data of the post categories 

$test = wp_get_post_categories( $post->ID, [ 'fields' => 'all' ] );

print_r( $test );

/* Displays:
Array
(
	[0] => stdClass Object
		(
			[term_id] => 1
			[name] => No Category
			[slug] => no-category
			[term_group] => 0
			[term_taxonomy_id] => 1
			[taxonomy] => category
			[description] =>
			[parent] => 0
			[count] => 2
			[filter] => raw
		)

	[1] => stdClass Object
		(
			[term_id] => 2
			[name] => Some category
			[slug] => some-category
			[term_group] => 0
			[term_taxonomy_id] => 2
			[taxonomy] => category
			[description] =>
			[parent] => 0
			[count] => 1
			[filter] => raw
		)

)
*/

foreach( $test as $cat ){
	echo $cat->name .'<br>';
}

/* Displays:
No Category<br>
Some category<br>
*/

Notes

Changelog

Since 2.1.0 Introduced.

wp_get_post_categories() code WP 7.0

wp-includes/post.php 
function wp_get_post_categories( $post_id = 0, $args = array() ) {
	$post_id = (int) $post_id;

	$defaults = array( 'fields' => 'ids' );
	$args     = wp_parse_args( $args, $defaults );

	$cats = wp_get_object_terms( $post_id, 'category', $args );
	return $cats;
}

For posts