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

Top ↑

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: ''

Top ↑

Return Return

(array) List of categories.

Top ↑

Source Source

File: wp-includes/category.php

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
function get_categories( $args = '' ) {
    $defaults = array( 'taxonomy' => 'category' );
    $args     = wp_parse_args( $args, $defaults );
 
    $taxonomy = $args['taxonomy'];
 
    /**
     * 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().
     */
    $taxonomy = apply_filters( 'get_categories_taxonomy', $taxonomy, $args );
 
    // Back compat
    if ( isset( $args['type'] ) && 'link' == $args['type'] ) {
        _deprecated_argument(
            __FUNCTION__,
            '3.0.0',
            /* translators: 1: "type => link", 2: "taxonomy => link_category" */
            sprintf(
                __( '%1$s is deprecated. Use %2$s instead.' ),
                '<code>type => link</code>',
                '<code>taxonomy => link_category</code>'
            )
        );
        $taxonomy = $args['taxonomy'] = 'link_category';
    }
 
    $categories = get_terms( $taxonomy, $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

Top ↑

Changelog Changelog

Changelog
Version Description
2.1.0 Introduced.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/category.php: _make_cat_compat()

Update category structure to old pre 2.3 from new taxonomy structure.
wp-includes/category.php: get_categories_taxonomy

Filters the taxonomy used to retrieve terms when calling get_categories().
wp-includes/functions.php: _deprecated_argument()

Mark a function argument as deprecated and inform when it has been used.
wp-includes/functions.php: wp_parse_args()

Merge user defined arguments into defaults array.
wp-includes/taxonomy.php: get_terms()

Retrieve the terms in a given taxonomy or list of taxonomies.
wp-includes/plugin.php: apply_filters()

Call the functions added to a filter hook.
wp-includes/load.php: is_wp_error()

Check whether variable is a WordPress Error.
Show 3 more uses Hide more uses

Top ↑

Used By Used By

Used By
Used By Description
wp-admin/includes/export.php: export_wp()

Generates the WXR export file for download.
wp-admin/includes/deprecated.php: wp_dropdown_cats()

Legacy function used for generating a categories drop-down control.
wp-includes/category-template.php: wp_list_categories()

Display or retrieve the HTML list of categories.
wp-includes/deprecated.php: get_links_list()

Output entire list of links by category.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::mw_getCategories()

Retrieve the list of categories on a given blog.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::mt_getCategoryList()

Retrieve list of all categories on blog.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::wp_suggestCategories()

Retrieve category list.
Show 2 more used by Hide more used by

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    <?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

  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    $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 )
        );
    }
  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Drop-down box as used in Parent category at post category page
    This is the code used in the built-in category page.

    1
    2
    3
    4
    5
    6
    7
    8
    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).

    1
    2
    3
    4
    5
    6
    wp_dropdown_categories( array(
        'hide_empty'   => 0,
        'name'         => 'select_name',
        'id'           => 'select_name',
        'hierarchical' => true
    ) );
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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”.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    <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

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