get_categories( string|array $args = '' )
Retrieve list of category objects.
Contents
Description Description
If you change the type to ‘link’ in the arguments, then the link categories will be returned instead. Also all categories will be updated to be backward compatible with pre-2.3 plugins and themes.
See also See also
- get_terms(): Type of arguments that can be changed.
Parameters Parameters
- $args
-
(string|array) (Optional) Arguments to retrieve categories. See get_terms() for additional options.
- 'taxonomy'
(string) Taxonomy to retrieve terms for. In this case, default 'category'.
Default value: ''
- 'taxonomy'
Return Return
(array) List of categories.
Source Source
File: wp-includes/category.php
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;
}
Expand full source code Collapse full source code View on Trac
Changelog Changelog
| Version | Description |
|---|---|
| 2.1.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
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>'; }Expand full source codeCollapse full source code
Get only top level categories
To get the top level categories only, set parent value to zero. This example gets link and name of top level categories.
$categories = get_categories( array( 'orderby' => 'name', 'parent' => 0 ) ); foreach ( $categories as $category ) { printf( '<a href="%1$s">%2$s</a><br />', esc_url( get_category_link( $category->term_id ) ), esc_html( $category->name ) ); }If there are no categories to display,
get_categories()will return an empty array.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' => falsein it. Check the example usage below.Drop-down box as used in Parent category at post category page
This is the code used in the built-in category page.
wp_dropdown_categories( array( 'hide_empty' => 0, 'name' => 'category_parent', 'orderby' => 'name', 'selected' => $category->parent, 'hierarchical' => true, 'show_option_none' => __('None') ) );The slightly altered code below will grab all categories and display them with indent for a new level (child category). The select box will have name and id attribute values of ‘select_name’. This select element will not display a default “none” as the original code was used to attach a category as a child to another category (or none).
Drop-down Box
Here’s how to create a drop-down box of the subcategories of, say, a category that archives information on past events.
This mirrors the example of the drop-down example of
wp_get_archives()which shows how to create a drop-down box for monthly archives.Suppose the category whose subcategories you want to show is category 10, and that its category “nicename” is “archives”.
<select name="event-dropdown"> <option value=""><?php echo esc_attr_e( 'Select Event', 'textdomain' ); ?></option> <?php $categories = get_categories( array( 'child_of' => 10 ) ); foreach ( $categories as $category ) { printf( '<option value="%1$s">%2$s (%3$s)</option>', esc_attr( '/category/archives/' . $category->category_nicename ), esc_html( $category->cat_name ), esc_html( $category->category_count ) ); } ?> </select>Expand full source codeCollapse full source code