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

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.

See also

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()

Return

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

Changelog

VersionDescription
2.1.0Introduced.

User Contributed Notes

  1. Skip to note 4 content

    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 );
    }
  2. Skip to note 5 content

    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;
    	}
    }
  3. Skip to note 6 content

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

You must log in before being able to contribute a note or feedback.