wppaste
WordPress

wp_get_archives( string|array $args = '' ): void|string

Since
1.2.0, 4.4.0, 5.2.0
Source
wp-includes/general-template.php:2207
Displays archive links based on type and format.

Compatibility

WordPress
since 5.2.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
Default archive links arguments. Optional.Default: ''

  • $typestringdefault: 'monthly'

    Type of archive to retrieve. Accepts 'daily', 'weekly', 'monthly', 'yearly', 'postbypost', or 'alpha'. Both 'postbypost' and 'alpha' display the same archive link list as well as post titles instead of displaying dates. The difference between the two is that 'alpha' will order by post title and 'postbypost' will order by post date.

  • $limitstring|intdefault: empty (no limit)

    Number of links to limit the query to.

  • $formatstringdefault: 'html'

    Format each link should take using the $before and $after args. Accepts 'link' (<link> tag), 'option' (<option> tag), 'html' (<li> tag), or a custom format, which generates a link anchor with $before preceding and $after succeeding.

  • $beforestringdefault: empty

    Markup to prepend to the beginning of each link.

  • $afterstringdefault: empty

    Markup to append to the end of each link.

  • $show_post_countbooldefault: false

    Whether to display the post count alongside the link.

  • $echobool|intdefault: 1|true to echo

    Whether to echo or return the links list.

  • $orderstringdefault: 'DESC'

    Whether to use ascending or descending order. Accepts 'ASC', or 'DESC'.

  • $post_typestringdefault: 'post'

    Post type.

  • $yearstringdefault: current year

    Year.

  • $monthnumstringdefault: current month number

    Month number.

  • $daystringdefault: current day

    Day.

  • $wstringdefault: current week

    Week.

Return value

void|string
Void if 'echo' argument is true, archive links if 'echo' is false.

Performance profile

How much work a call to wp_get_archives() 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

Reaches the database via ->get_results().

Scaling
Scales with input

The body loops, so the work grows with what you pass in.

Instructions
110–168

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 699.

Plugin surface
4 hooks

Third-party callbacks on 'wp_get_archives_args', 'getarchives_where', 'getarchives_join' run inside this call, and their cost is not bounded by anything here.

Called by
3

3 places in core call this, so the cost is paid more often than your own code shows.

What it touches

  • hookthird-party callbacksapply_filters()called directly
  • cacheobject cachewp_cache_get_last_changed()called directly
  • optionoption read or writeget_option()called directly
  • sqldatabase query->get_results()called directly
  • serializeserialisationmaybe_unserialize()one call below wp_get_archives()
  • querycontent queryget_post()one call below wp_get_archives()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 10 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_get_archives() can have, taken from its control-flow graph on PHP 8.5.

WhenInstructionsCalls it makes
is_post_type_viewable() && empty($parsed_args)110–114get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed()
is_post_type_viewable() && !empty($parsed_args)121–123get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), absint(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed()
is_post_type_viewable() && empty($parsed_args)124–148get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed(), md5(), wp_cache_get_salted()
is_post_type_viewable() && empty($parsed_args)130–159get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed(), md5(), wp_cache_get_salted(), ->get_results(), wp_cache_set_salted()
is_post_type_viewable() && !empty($parsed_args)135–157get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), absint(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed(), md5(), wp_cache_get_salted()
is_post_type_viewable() && empty($parsed_args)138–148get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed(), _wp_mysql_week(), md5(), wp_cache_get_salted()
is_post_type_viewable() && !empty($parsed_args)141–168get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), absint(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed(), md5(), wp_cache_get_salted(), ->get_results(), wp_cache_set_salted()
is_post_type_viewable() && empty($parsed_args)148–158get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed(), _wp_mysql_week(), md5(), wp_cache_get_salted(), ->get_results(), wp_cache_set_salted()
is_post_type_viewable() && !empty($parsed_args)149–157get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), absint(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed(), _wp_mysql_week(), md5(), wp_cache_get_salted()
is_post_type_viewable() && !empty($parsed_args)159–167get_query_var(), get_query_var(), get_query_var(), get_query_var(), apply_filters(), wp_parse_args(), get_post_type_object(), is_post_type_viewable(), absint(), strtoupper(), ->prepare(), apply_filters(), apply_filters(), wp_cache_get_last_changed(), _wp_mysql_week(), md5(), wp_cache_get_salted(), ->get_results(), wp_cache_set_salted()

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Across PHP versions

PHPCompiledExecutedBranchesNotes
8.6-dev699110–16851
8.5699110–16851
8.4699110–168512 fewer instructions than PHP 8.3
8.3701110–16851
8.2701110–16851
8.1701110–16851
7.4701110–16851

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 · 4

4 hooks fire while wp_get_archives() runs, in this order:

  1. apply_filters( wp_get_archives_args )filterline 2235 (+28 into the body)

    Filters the arguments for displaying archive links.

  2. apply_filters( getarchives_where )filterline 2273 (+66 into the body)

    Filters the SQL WHERE clause for retrieving archives.

  3. apply_filters( getarchives_join )filterline 2283 (+76 into the body)

    Filters the SQL JOIN clause for retrieving archives.

  4. apply_filters( the_title )filterline 2420 (+213 into the body)

    Filters the post title.

Uses · 24

Show all 24
  • is_archive()Determines whether the query is for an existing archive page.
  • get_archives_link()Retrieves archive link content based on predefined or custom code.
  • get_year_link()Retrieves the permalink for the year archives.
  • get_day_link()Retrieves the permalink for the day archives with year and month.
  • mysql2date()Converts given MySQL date string into a different format.
  • get_option()Retrieves an option value based on an option name.
  • _wp_mysql_week()Returns a MySQL expression for selecting the week number based on the start_of_week option.
  • get_weekstartend()Gets the week start and end from the datetime or date string from MySQL.
  • date_i18n()Retrieves the date in localized format, based on a sum of Unix timestamp and timezone offset in seconds.
  • home_url()Retrieves the URL for the current site where the front end is accessible.
  • get_permalink()Retrieves the full permalink for the current post or post ID.
  • get_the_ID()Retrieves the ID of the current item in the WordPress Loop.

Used by · 3

Source code

View on Trac View on GitHub 

function wp_get_archives( $args = '' ) {	global $wpdb, $wp_locale; 	$defaults = array(		'type'            => 'monthly',		'limit'           => '',		'format'          => 'html',		'before'          => '',		'after'           => '',		'show_post_count' => false,		'echo'            => 1,		'order'           => 'DESC',		'post_type'       => 'post',		'year'            => get_query_var( 'year' ),		'monthnum'        => get_query_var( 'monthnum' ),		'day'             => get_query_var( 'day' ),		'w'               => get_query_var( 'w' ),	); 	/**	 * Filters the arguments for displaying archive links.	 *	 * @since 7.0.0	 *	 * @see wp_get_archives()	 *	 * @param array<string, string|int|bool> $args Arguments.	 */	$args = apply_filters( 'wp_get_archives_args', $args ); 	$parsed_args = wp_parse_args( $args, $defaults ); 	$post_type_object = get_post_type_object( $parsed_args['post_type'] );	if ( ! is_post_type_viewable( $post_type_object ) ) {		return;	} 	$parsed_args['post_type'] = $post_type_object->name; 	if ( '' === $parsed_args['type'] ) {		$parsed_args['type'] = 'monthly';	} 	if ( ! empty( $parsed_args['limit'] ) ) {		$parsed_args['limit'] = absint( $parsed_args['limit'] );		$parsed_args['limit'] = ' LIMIT ' . $parsed_args['limit'];	} 	$order = strtoupper( $parsed_args['order'] );	if ( 'ASC' !== $order ) {		$order = 'DESC';	} 	// This is what will separate dates on weekly archive links.	$archive_week_separator = '&#8211;'; 	$sql_where = $wpdb->prepare( "WHERE post_type = %s AND post_status = 'publish'", $parsed_args['post_type'] ); 	/**	 * Filters the SQL WHERE clause for retrieving archives.	 *	 * @since 2.2.0	 *	 * @param string $sql_where   Portion of SQL query containing the WHERE clause.	 * @param array  $parsed_args An array of default arguments.	 */	$where = apply_filters( 'getarchives_where', $sql_where, $parsed_args ); 	/**	 * Filters the SQL JOIN clause for retrieving archives.	 *	 * @since 2.2.0	 *	 * @param string $sql_join    Portion of SQL query containing JOIN clause.	 * @param array  $parsed_args An array of default arguments.	 */	$join = apply_filters( 'getarchives_join', '', $parsed_args ); 	$output = '';

Changelog

Introduced in 1.2.0. Unchanged from 6.7.7 through 7.1.0.

  1. 6.7.7
  2. 6.8.8
  3. 6.9.7
  4. 7.0.4
  5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

5.2.0
The $year, $monthnum, $day, and $w arguments were added.from the docblock
4.4.0
The $post_type argument was added.from the docblock
1.2.0
Introduced.from the docblock

About this page

Parsed data
Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/general-template.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.