wppaste
WordPress

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

Since
2.1.0
Source
wp-includes/bookmark-template.php:211
Retrieves or echoes all of the bookmarks.

Description

List of default arguments are as follows:

These options define how the Category name will appear before the category links are displayed, if 'categorize' is 1. If 'categorize' is 0, then it will display for only the 'title_li' string and only if 'title_li' is not empty.

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
String or array of arguments to list bookmarks.Default: ''

  • $orderbystringdefault: 'name'

    How to order the links by. Accepts post fields.

  • $orderstringdefault: 'ASC'

    Whether to order bookmarks in ascending or descending order. Accepts 'ASC' (ascending) or 'DESC' (descending).

  • $limitintdefault: -1

    Amount of bookmarks to display. Accepts 1+ or -1 for all.

  • $categorystringdefault: empty

    Comma-separated list of category IDs to include links from.

  • $category_namestringdefault: empty

    Category to retrieve links for by name.

  • $hide_invisibleint|booldefault: 1|true

    Whether to show or hide links marked as 'invisible'. Accepts 1|true or 0|false.

  • $show_updatedint|booldefault: 0|false

    Whether to display the time the bookmark was last updated. Accepts 1|true or 0|false.

  • $echoint|booldefault: 1|true

    Whether to echo or return the formatted bookmarks. Accepts 1|true (echo) or 0|false (return).

  • $categorizeint|booldefault: 1|true

    Whether to show links listed by category or in a single column. Accepts 1|true (by category) or 0|false (one column).

  • $show_descriptionint|booldefault: 0|false

    Whether to show the bookmark descriptions. Accepts 1|true or 0|false.

  • $title_listringdefault: 'Bookmarks'

    What to show before the links appear.

  • $title_beforestringdefault: ''

    The HTML or text to prepend to the $title_li string.

  • $title_afterstringdefault: ''

    The HTML or text to append to the $title_li string.

  • $classstring|arraydefault: 'linkcat'

    The CSS class or an array of classes to use for the $title_li.

  • $category_beforestringdefault: ''

    The HTML or text to prepend to $title_before if $categorize is true. String must contain '%id' and '%class' to inherit the category ID and the $class argument used for formatting in themes.

  • $category_afterstringdefault: ''

    The HTML or text to append to $title_after if $categorize is true.

  • $category_orderbystringdefault: 'name'

    How to order the bookmark category based on term scheme if $categorize is true.

  • $category_orderstringdefault: 'ASC'

    Whether to order categories in ascending or descending order if $categorize is true. Accepts 'ASC' (ascending) or 'DESC' (descending).

Return value

void|string
Void if 'echo' argument is true, HTML list of bookmarks if 'echo' is false.

Performance profile

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

Scaling
Scales with input

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

Instructions
60–118

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

Plugin surface
2 hooks

Third-party callbacks on 'link_category', 'wp_list_bookmarks' 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

  • querycontent queryget_terms()called directly
  • hookthird-party callbacksapply_filters()called directly
  • cacheobject cachewp_cache_get()one call below wp_list_bookmarks()
  • optionoption read or writeget_option()one call below wp_list_bookmarks()

Further down the call graph this can also reach 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 · 12 distinct outcomes

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

WhenInstructionsCalls it makes
always60–62__(), wp_parse_args(), array_map(), apply_filters()
!$parsed_args && empty($bookmarks)62–63__(), wp_parse_args(), array_map(), get_bookmarks(), apply_filters()
always67–69__(), wp_parse_args(), explode(), array_map(), apply_filters()
!$parsed_args && !empty($bookmarks)69–91__(), wp_parse_args(), array_map(), get_bookmarks(), _walk_bookmarks(), apply_filters()
!$parsed_args && empty($bookmarks)69–70__(), wp_parse_args(), explode(), array_map(), get_bookmarks(), apply_filters()
!$parsed_args && !empty($bookmarks)76–98__(), wp_parse_args(), explode(), array_map(), get_bookmarks(), _walk_bookmarks(), apply_filters()
$parsed_args78–82__(), wp_parse_args(), array_map(), link_category(), apply_filters()
empty($bookmarks)80–83__(), wp_parse_args(), array_map(), link_category(), get_bookmarks(), apply_filters()
$parsed_args85–89__(), wp_parse_args(), explode(), array_map(), link_category(), apply_filters()
!empty($bookmarks)87–111__(), wp_parse_args(), array_map(), link_category(), get_bookmarks(), _walk_bookmarks(), apply_filters()
empty($bookmarks)87–90__(), wp_parse_args(), explode(), array_map(), link_category(), get_bookmarks(), apply_filters()
!empty($bookmarks)94–118__(), wp_parse_args(), explode(), array_map(), link_category(), get_bookmarks(), _walk_bookmarks(), apply_filters()

Across PHP versions

PHPCompiledExecutedBranchesNotes
8.6-dev17460–11810
8.517460–11810
8.417460–1181011 fewer instructions than PHP 8.3
8.318565–12610
8.218565–12610
8.118565–12610
7.418565–12610

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

2 hooks fire while wp_list_bookmarks() runs, in this order:

  1. apply_filters( link_category )filterline 280 (+69 into the body)

    Filters the category name.

  2. apply_filters( wp_list_bookmarks )filterline 321 (+110 into the body)

    Filters the bookmarks list before it is echoed or returned.

Uses · 6

Used by · 3

Source code

View on Trac View on GitHub 

function wp_list_bookmarks( $args = '' ) {	$defaults = array(		'orderby'          => 'name',		'order'            => 'ASC',		'limit'            => -1,		'category'         => '',		'exclude_category' => '',		'category_name'    => '',		'hide_invisible'   => 1,		'show_updated'     => 0,		'echo'             => 1,		'categorize'       => 1,		'title_li'         => __( 'Bookmarks' ),		'title_before'     => '<h2>',		'title_after'      => '</h2>',		'category_orderby' => 'name',		'category_order'   => 'ASC',		'class'            => 'linkcat',		'category_before'  => '<li id="%id" class="%class">',		'category_after'   => '</li>',	); 	$parsed_args = wp_parse_args( $args, $defaults ); 	$output = ''; 	if ( ! is_array( $parsed_args['class'] ) ) {		$parsed_args['class'] = explode( ' ', $parsed_args['class'] );	}	$parsed_args['class'] = array_map( 'sanitize_html_class', $parsed_args['class'] );	$parsed_args['class'] = trim( implode( ' ', $parsed_args['class'] ) ); 	if ( $parsed_args['categorize'] ) {		$cats = get_terms(			array(				'taxonomy'     => 'link_category',				'name__like'   => $parsed_args['category_name'],				'include'      => $parsed_args['category'],				'exclude'      => $parsed_args['exclude_category'],				'orderby'      => $parsed_args['category_orderby'],				'order'        => $parsed_args['category_order'],				'hierarchical' => 0,			)		);		if ( empty( $cats ) ) {			$parsed_args['categorize'] = false;		}	} 	if ( $parsed_args['categorize'] ) {		// Split the bookmarks into ul's for each category.		foreach ( (array) $cats as $cat ) {			$params    = array_merge( $parsed_args, array( 'category' => $cat->term_id ) );			$bookmarks = get_bookmarks( $params );			if ( empty( $bookmarks ) ) {				continue;			}			$output .= str_replace(				array( '%id', '%class' ),				array( "linkcat-$cat->term_id", $parsed_args['class'] ),				$parsed_args['category_before']			);			/**			 * Filters the category name.			 *			 * @since 2.2.0			 *			 * @param string $cat_name The category name.			 */			$catname = apply_filters( 'link_category', $cat->name ); 			$output .= $parsed_args['title_before'];			$output .= $catname;			$output .= $parsed_args['title_after'];			$output .= "\n\t<ul class='xoxo blogroll'>\n";			$output .= _walk_bookmarks( $bookmarks, $parsed_args );			$output .= "\n\t</ul>\n";			$output .= $parsed_args['category_after'] . "\n";		}	} else {

Changelog

Introduced in 2.1.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.

About this page

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