wp_get_post_categories() – Function | Developer.WordPress.org

Retrieves the list of categories for a post.

Description

Compatibility layer for themes and plugins. Also an easy layer of abstraction away from the complexity of the taxonomy layer.

Parameters

$post_idintoptional: The Post ID. Does not default to the ID of the global $post. Default 0.
$argsarrayoptional: Category query parameters.
See WP_Term_Query::__construct() for supported arguments.
Default:array()

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. If $fields is 'ids', an array of category IDs. If $fields is 'names', an array of category names.
WP_Error object if 'category' taxonomy doesn’t exist.

More Information

The results from wp_get_post_categories() aren’t cached which will result in a database call being made every time this function is called. Use this function with care. For performance, functions like get_the_category() should be used to return categories attached to a post.

Source

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;
}

View all references View on Trac View on GitHub

Uses	Description
wp_get_object_terms()`wp-includes/taxonomy.php`	Retrieves the terms associated with the given object(s), in the supplied taxonomies.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.

Used by	Description
bulk_edit_posts()`wp-admin/includes/post.php`	Processes the post data for the bulk editing of posts.
wp_get_post_cats()`wp-includes/deprecated.php`	Retrieves a list of post categories.
wp_xmlrpc_server::mt_getPostCategories()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves post categories.
wp_xmlrpc_server::mt_publishPost()`wp-includes/class-wp-xmlrpc-server.php`	Sets a post’s publish status to ‘publish’.
wp_xmlrpc_server::mw_getPost()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves a post.
wp_xmlrpc_server::mw_getRecentPosts()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves list of recent posts.
wp_xmlrpc_server::blogger_getPost()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves a post.
wp_xmlrpc_server::blogger_getRecentPosts()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves the list of recent posts.
wp_xmlrpc_server::_prepare_page()`wp-includes/class-wp-xmlrpc-server.php`	Prepares page data for return in an XML-RPC object.

Show 4 more Show less

Changelog

Version	Description
2.1.0	Introduced.

User Contributed Notes

Skip to note 4 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note
The example below shows how categories are retrieved, and then additional information is retrieved for each category.
```
$post_categories = wp_get_post_categories( $post_id );
$cats = array();
	
foreach($post_categories as $c){
	$cat = get_category( $c );
	$cats[] = array( 'name' => $cat->name, 'slug' => $cat->slug );
}
```
- It is possible to retrieve all the additional information directly from the call to the function with the args parameter as described in the return description:
  
  $post_categories = wp_get_post_categories( $post_id, array ( ‘fields’ = > ‘all’ ) );
  
  paquinfrancis 5 years ago
- There is now a better way to retrieve more information. I’ll be adding example bellow
  
  Sabbir Hasan 4 years ago
Log in to add feedback

Sabbir Hasan 4 years ago

The example below shows how categories are retrieved, and using arguments additional info will be retrieved instead of calling get_category

$post_categories = wp_get_post_categories( $post_id, array( 'fields' => 'all' ) );
$cats = array();

if( $post_categories ){ // Always Check before loop!
	foreach($post_categories as $c){
		$cats[] = array( 'name' => $c->name, 'slug' => $c->slug );
		// Or we can just print it directly
		printf("Category Name: %s, Category Slug: %s, Category Url: %s <br/>", $c->name, $c->slug, esc_url( get_category_link( $c->term_id ) ) );
	}	
}

Only list Category names:

$post_categories = wp_get_post_categories( $post_id, array( 'fields' => 'names' ) );

if( $post_categories ){ // Always Check before loop!
	foreach($post_categories as $name){
		echo $name;
	}
}

Akramul Hasan 3 years ago

List category names in Descending order:

$terms_list = wp_get_post_categories( $post_id, array( 'fields'=>'names', 'order'=> 'DESC' ) );
if ( $terms_list ) { // Check $terms_list has value
	foreach ( $terms_list as $term ) {
		echo esc_html( $term ) . '<br />';
	}
}

If you want to exclude any specific term from the list you can do like:

// Add the 'exclude' key and put the term id you wanted to exclude from the result as key
// If you want to exclude multiple terms, then put their keys separated by a comma or space

$terms_list = wp_get_post_categories( $post_id, array( 'fields'=>'names', 'exclude'=> '1,7' ) );
if ( $terms_list ) { // Check $terms_list has value
	foreach ( $terms_list as $term ) {
		echo esc_html( $term ) . '<br />';
	}
}

wp_get_post_categories( int $post_id, array $args = array() ): array|WP_Error

In this article