get_categories( string|array $args = '' ): array
- Since
- 2.1.0
- Source
wp-includes/category.php:26
Description
If you set the 'taxonomy' argument to 'link_category', the link categories will be returned instead.
Compatibility
- WordPress
- since 2.1.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$argsstring|arrayoptional- Arguments to retrieve categories. See get_terms() for additional options.Default:
''$taxonomystringdefault: 'category'Taxonomy to retrieve terms for.
Return value
array- List of category objects.
Performance profile
How much work a call to get_categories() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Heavy
- Scaling
- Scales with input
- Instructions
- 28–53
- Plugin surface
- 1 hook
- Called by
- 11
Reaches the database via get_terms().
The body loops, so the work grows with what you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 61.
Third-party callbacks on 'get_categories_taxonomy' run inside this call, and their cost is not bounded by anything here.
11 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()called directly - querycontent query
get_terms()called directly
Further down the call graph this can also reach option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 4 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost get_categories() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
is_wp_error() | 28–31 | wp_parse_args(), apply_filters(), get_terms(), is_wp_error() |
!is_wp_error() | 34–38 | wp_parse_args(), apply_filters(), get_terms(), is_wp_error(), array_keys() |
isset($args) && is_wp_error() | 46 | wp_parse_args(), apply_filters(), __(), sprintf(), _deprecated_argument(), get_terms(), is_wp_error() |
isset($args) && !is_wp_error() | 52–53 | wp_parse_args(), apply_filters(), __(), sprintf(), _deprecated_argument(), get_terms(), is_wp_error(), array_keys() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 61 instructions, 28–53 executed per call, 5 branches. The work does not change between versions.
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Hooks and filters fired · 1
One hook fires while get_categories() runs, in this order:
- apply_filters( get_categories_taxonomy )filterline 38 (+12 into the body)
Filters the taxonomy used to retrieve terms when calling get_categories().
Uses · 7
- wp_parse_args()Merges user defined arguments into defaults array.
- apply_filters()Calls the callback functions that have been added to a filter hook.
- _deprecated_argument()Marks a function argument as deprecated and inform when it has been used.
- __()Retrieves the translation of $text.
- get_terms()Retrieves the terms in a given taxonomy or list of taxonomies.
- is_wp_error()Checks whether the given variable is a WordPress Error.
- _make_cat_compat()Updates category structure to old pre-2.3 from new taxonomy structure.
Used by · 11
- export_wp()Generates the WXR export file for download.
- get_links_list()Output entire list of links by category.
- twentyfifteen_categorized_blog()Determines whether blog/site has more than one category.
- twentyfourteen_categorized_blog()Finds out if blog has more than one category.
- twentyseventeen_categorized_blog()Returns true if a blog has more than 1 category.
- twentysixteen_categorized_blog()Determines whether blog/site has more than one category.
- wp_dropdown_cats()Legacy function used for generating a categories drop-down control.
- wp_list_categories()Displays or retrieves the HTML list of categories.
- wp_xmlrpc_server::mt_getCategoryList()Retrieves the list of all categories on a blog.
- wp_xmlrpc_server::mw_getCategories()Retrieves the list of categories on a given blog.
- wp_xmlrpc_server::wp_suggestCategories()Retrieves category list.
Source code
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;}Changelog
Introduced in 2.1.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.0.4 tag, from
src/wp-includes/category.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.