get_archives_link( string $url, string $text, string $format = 'html', string $before = '', string $after = '', bool $selected = false ): string
- Since
- 1.0.0, 5.2.0
- Source
wp-includes/general-template.php:1922
Description
The format can be one of four styles. The 'link' for head element, 'option' for use in the select element, 'html' for use in list (either ol or ul HTML elements). Custom content is also supported using the before and after parameters.
The 'link' format uses the <link> HTML element with the archives relationship. The before and after parameters are not used. The text parameter is used to describe the link.
The 'option' format uses the option HTML element for use in select element.
The value is the url parameter and the before and after parameters are used between the text description.
The 'html' format, which is the default, uses the li HTML element for use in the list HTML elements. The before parameter is before the link and the after parameter is after the closing link.
The custom format uses the before parameter before the link ('a' HTML element) and the after parameter after the closing link tag. If the above three values for the format are not used, then custom format is assumed.
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
$urlstring- URL to archive.
$textstring- Archive text description.
$formatstringoptional- Can be 'link', 'option', 'html', or custom. Default 'html'.Default:
'html' $beforestringoptional- Content to prepend to the description. Default empty.Default:
'' $afterstringoptional- Content to append to the description. Default empty.Default:
'' $selectedbooloptional- Set to true if the current page is the selected archive page. Default false.Default:
false
Return value
string- HTML link content for archive.
Performance profile
How much work a call to get_archives_link() 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
- Trivial
- Scaling
- Constant
- Instructions
- 39–49
- Plugin surface
- 1 hook
- Called by
- 1
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 85.
Third-party callbacks on 'get_archives_link' run inside this call, and their cost is not bounded by anything here.
1 place 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
Further down the call graph this can also reach option, cache, serialize, query 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 · 2 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost get_archives_link() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
$format === "link" | 39–40 | wptexturize(), esc_url(), esc_attr(), apply_filters() |
$format !== "link" | 45–49 | wptexturize(), esc_url(), apply_filters() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 85 instructions, 39–49 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_archives_link() runs, in this order:
- apply_filters( get_archives_link )filterline 1953 (+31 into the body)
Filters the archive link content.
Uses · 4
- wptexturize()Replaces common plain text characters with formatted entities.
- esc_url()Checks and cleans a URL.
- esc_attr()Escaping for HTML attributes.
- apply_filters()Calls the callback functions that have been added to a filter hook.
Used by · 1
- wp_get_archives()Displays archive links based on type and format.
Source code
function get_archives_link( $url, $text, $format = 'html', $before = '', $after = '', $selected = false ) { $text = wptexturize( $text ); $url = esc_url( $url ); $aria_current = $selected ? ' aria-current="page"' : ''; if ( 'link' === $format ) { $link_html = "\t<link rel='archives' title='" . esc_attr( $text ) . "' href='$url' />\n"; } elseif ( 'option' === $format ) { $selected_attr = $selected ? " selected='selected'" : ''; $link_html = "\t<option value='$url'$selected_attr>$before $text $after</option>\n"; } elseif ( 'html' === $format ) { $link_html = "\t<li>$before<a href='$url'$aria_current>$text</a>$after</li>\n"; } else { // Custom. $link_html = "\t$before<a href='$url'$aria_current>$text</a>$after\n"; } /** * Filters the archive link content. * * @since 2.6.0 * @since 4.5.0 Added the `$url`, `$text`, `$format`, `$before`, and `$after` parameters. * @since 5.2.0 Added the `$selected` parameter. * * @param string $link_html The archive HTML link content. * @param string $url URL to archive. * @param string $text Archive text description. * @param string $format Link format. Can be 'link', 'option', 'html', or custom. * @param string $before Content to prepend to the description. * @param string $after Content to append to the description. * @param bool $selected True if the current page is the selected archive. */ return apply_filters( 'get_archives_link', $link_html, $url, $text, $format, $before, $after, $selected );}Changelog
Introduced in 1.0.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
$selected parameter.from the docblockAbout this page
- Parsed data
- Generated from the wordpress-develop 6.8.8 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.