WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

get_categories()

get_categories( string|array $args = '' ): array

In this article

Back to top

Retrieves a list of category objects.

Description

If you set the ‘taxonomy’ argument to ‘link_category’, the link categories will be returned instead.

See also

Parameters

$argsstring|arrayoptional
Arguments to retrieve categories. See get_terms() for additional options.
  • taxonomy string
    Taxonomy to retrieve terms for. Default 'category'.
More Arguments from get_terms( … $args )Array or string of arguments. See WP_Term_Query::__construct() for information on accepted arguments.

Default:''

Return

array List of category objects.

Source

function get_categories( $args = '' ) {
	$defaults = array( 'taxonomy' => 'category' );
	$args     = wp_parse_args( $args, $defaults );

	/**
	 * Filters the taxonomy used to retrieve terms when calling get_categories().
	 *
	 * @since 2.7.0
	 *
	 * @param string $taxonomy Taxonomy to retrieve terms from.
	 * @param array  $args     An array of arguments. See get_terms().
	 */
	$args['taxonomy'] = apply_filters( 'get_categories_taxonomy', $args['taxonomy'], $args );

	// Back compat.
	if ( isset( $args['type'] ) && 'link' === $args['type'] ) {
		_deprecated_argument(
			__FUNCTION__,
			'3.0.0',
			sprintf(
				/* translators: 1: "type => link", 2: "taxonomy => link_category" */
				__( '%1$s is deprecated. Use %2$s instead.' ),
				'<code>type => link</code>',
				'<code>taxonomy => link_category</code>'
			)
		);
		$args['taxonomy'] = 'link_category';
	}

	$categories = get_terms( $args );

	if ( is_wp_error( $categories ) ) {
		$categories = array();
	} else {
		$categories = (array) $categories;
		foreach ( array_keys( $categories ) as $k ) {
			_make_cat_compat( $categories[ $k ] );
		}
	}

	return $categories;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_categories_taxonomy’, string $taxonomy, array $args )

Filters the taxonomy used to retrieve terms when calling get_categories() .

UsesDescription
_make_cat_compat()wp-includes/category.php

Updates category structure to old pre-2.3 from new taxonomy structure.

get_terms()wp-includes/taxonomy.php

Retrieves the terms in a given taxonomy or list of taxonomies.

_deprecated_argument()wp-includes/functions.php

Marks a function argument as deprecated and inform when it has been used.

wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.

apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.

Show 4 moreShow less
Used byDescription
wp_dropdown_cats()wp-admin/includes/deprecated.php

Legacy function used for generating a categories drop-down control.

wp_list_categories()wp-includes/category-template.php

Displays or retrieves the HTML list of categories.

get_links_list()wp-includes/deprecated.php

Output entire list of links by category.

wp_xmlrpc_server::mw_getCategories()wp-includes/class-wp-xmlrpc-server.php

Retrieves the list of categories on a given blog.

wp_xmlrpc_server::mt_getCategoryList()wp-includes/class-wp-xmlrpc-server.php

Retrieves the list of all categories on a blog.

wp_xmlrpc_server::wp_suggestCategories()wp-includes/class-wp-xmlrpc-server.php

Retrieves category list.

Show 1 moreShow less

Changelog

VersionDescription
2.1.0Introduced.

User Contributed Notes

  1. Skip to note 9 content
    Codex
    You must log in to vote on the helpfulness of this noteVote results for this note: 16You must log in to vote on the helpfulness of this note

    List Categories and Descriptions
    This example will list, in alphabetic order, all categories presented as links to the corresponding category archive. Each category description is listed after the category link.

    <?php
$categories = get_categories( array(
	'orderby' => 'name',
	'order'   => 'ASC'
) );

foreach( $categories as $category ) {
	$category_link = sprintf( 
		'<a href="%1$s" alt="%2$s">%3$s</a>',
		esc_url( get_category_link( $category->term_id ) ),
		esc_attr( sprintf( __( 'View all posts in %s', 'textdomain' ), $category->name ) ),
		esc_html( $category->name )
	);
	
	echo '<p>' . sprintf( esc_html__( 'Category: %s', 'textdomain' ), $category_link ) . '</p> ';
	echo '<p>' . sprintf( esc_html__( 'Description: %s', 'textdomain' ), $category->description ) . '</p>';
	echo '<p>' . sprintf( esc_html__( 'Post Count: %s', 'textdomain' ), $category->count ) . '</p>';
}
  2. Skip to note 10 content
    isMike()
    You must log in to vote on the helpfulness of this noteVote results for this note: 12You must log in to vote on the helpfulness of this note

    Function only returns categories in use by posts

    It is very important to note that by default, the get_category() will ONLY return categories that ARE IN USE. This means if no post is assigned to the category, then the category object for that category is not returned.

    This means if you are developer, and you created a category (maybe during testing), you should supply an argument array having the 'hide_empty' => false in it. Check the example usage below.

    $args = array(
			'hide_empty'      => false,
		);
		get_categories($args); //This returns both used and unused categories