get_archives_link() │ WP 1.0.0

Gets the link to the archive page. Assembles the link from the provided: URL, link anchor, output format, text before and after.

This is a helper function that assembles the HTML link tag in the format specified in the $format parameter:

The text is processed by the filters: wptexturize() and esc_attr(), and the link by esc_url(), and as a result, we will get cleaned text, even if incorrect characters are passed to the function.

Hooks from the function

Returns

String. HTML tag A.

Usage

get_archives_link( $url, $text, $format, $before, $after );
$url(string) (required)
URL link: http://example.com/2013.
$text(string) (required)
Link anchor (description of the link, text that will be shown as a link).
$format(string)

In what format to output the link:

  • html - for use in lists: ul or ol;
  • link - for use in the head part of the HTML code;
  • option - for use in select form elements;
  • custom - another format, leave this field empty and use the before and after parameters.

Default: html

$before(string)
Text before the link, HTML code can be specified.
Default: ''
$after(string)
Text after the link, HTML code can be specified.
Default: ''

Examples

0

#1 Examples showing what the function returns: 

echo get_archives_link( '/2013', '2013 Archive' );
// <li><a href='/2013' title='Archive for 2013'>Archive for 2013</a></li>

get_archives_link( '/2013', '2013 Archive', 'link' );
// <link rel='archives' title='Archive for 2013' href='/2013' />

get_archives_link( '/2013', '2013 Archive', 'option' );
// <option value='/2013'> Archive for 2013 </option>

get_archives_link( '/2013', '2013 Archive', '', '<div>','</div>' );
// <div><a href='/2013' title='Archive for 2013'>Archive for 2013</a></div>
0

#2 Wrap the number of posts in the archive widget in HTML

Let's add a <span> around the number of posts in the archive widget. This allows you to easily style the number of posts.

add_filter( 'get_archives_link', 'wpdocs_archive_count_span' );

/**
 * Adds a span around post counts in the archive widget.
 *
 * @param   string  $links      The comment fields.
 * @return  string
 */
function wpdocs_archive_count_span( $links ) {

	$links = str_replace( '</a> (', '<span class="count">', $links );
	$links = str_replace( ')', '</span></a>', $links );

	return $links;
}

Changelog

Since 1.0.0 Introduced.
Since 5.2.0 Added the $selected parameter.

get_archives_link() code WP 6.9

wp-includes/general-template.php 
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 );
}

Main Functions