get_bookmarks( string|array $args = '' ): object[]

Description

Compatibility

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 retrieve bookmarks.Default: ''

• $orderbystringdefault: 'name'

  How to order the links by. Accepts 'id', 'link_id', 'name', 'link_name', 'url', 'link_url', 'visible', 'link_visible', 'rating', 'link_rating', 'owner', 'link_owner', 'updated', 'link_updated', 'notes', 'link_notes', 'description', 'link_description', 'length' and 'rand'. When $orderby is 'length', orders by the character length of 'link_name'.

• $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 any positive number 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.

• $includestringdefault: empty

  Comma-separated list of bookmark IDs to include.

• $excludestringdefault: empty

  Comma-separated list of bookmark IDs to exclude.

• $searchstringdefault: empty

  Search terms. Will be SQL-formatted with wildcards before and after and searched in 'link_url', 'link_name' and 'link_description'.

Return value

object[]

List of bookmark row objects.

Performance profile

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

Scaling

Scales with input

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

Instructions

116–164

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

Plugin surface

1 hook

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

Called by

4

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

What it touches

• cacheobject cachewp_cache_get()called directly
• hookthird-party callbacksapply_filters()called directly
• serializeserialisationserialize()called directly
• sqldatabase query->get_results()called directly
• querycontent queryget_term()one call below get_bookmarks()

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

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

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

Hooks and filters fired · 3

3 hooks fire while get_bookmarks() runs, in this order:

1. 1
   apply_filters( get_bookmarks )filterline 175 (+39 into the body)

   Filters the returned list of bookmarks.

2. 2
   apply_filters( get_bookmarks )filterline 229 (+93 into the body)

   Filters the returned list of bookmarks.

3. 3
   apply_filters( get_bookmarks )filterline 322 (+186 into the body)

   Filters the returned list of bookmarks.

Uses · 7

• wp_parse_args()Merges user defined arguments into defaults array.
• wp_cache_get()Retrieves the cache contents from the cache by key and group.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_parse_id_list()Cleans up an array, comma- or space-separated list of IDs.
• get_term_by()Gets all term data from database by term field and data.
• wp_cache_set()Saves the data to the cache.
• absint()Converts a value to non-negative integer.

Used by · 4

• WP_Links_List_Table::prepare_items()
• get_linkobjects()Gets an array of link objects associated with category n.
• get_links()Gets the links associated with category by ID.
• wp_list_bookmarks()Retrieves or echoes all of the bookmarks.

Source code

View on Trac ↗View on GitHub ↗

136function get_bookmarks( $args = '' ) {137	global $wpdb;138 139	$defaults = array(140		'orderby'        => 'name',141		'order'          => 'ASC',142		'limit'          => -1,143		'category'       => '',144		'category_name'  => '',145		'hide_invisible' => 1,146		'show_updated'   => 0,147		'include'        => '',148		'exclude'        => '',149		'search'         => '',150	);151 152	$parsed_args = wp_parse_args( $args, $defaults );153 154	$key   = md5( serialize( $parsed_args ) );155	$cache = wp_cache_get( 'get_bookmarks', 'bookmark' );156 157	if ( 'rand' !== $parsed_args['orderby'] && $cache ) {158		if ( is_array( $cache ) && isset( $cache[ $key ] ) ) {159			$bookmarks = $cache[ $key ];160			/**161			 * Filters the returned list of bookmarks.162			 *163			 * The first time the hook is evaluated in this file, it returns the cached164			 * bookmarks list. The second evaluation returns a cached bookmarks list if the165			 * link category is passed but does not exist. The third evaluation returns166			 * the full cached results.167			 *168			 * @since 2.1.0169			 *170			 * @see get_bookmarks()171			 *172			 * @param array $bookmarks   List of the cached bookmarks.173			 * @param array $parsed_args An array of bookmark query arguments.174			 */175			return apply_filters( 'get_bookmarks', $bookmarks, $parsed_args );176		}177	}178 179	if ( ! is_array( $cache ) ) {180		$cache = array();181	}182 183	$inclusions = '';184	if ( ! empty( $parsed_args['include'] ) ) {185		$parsed_args['exclude']       = '';  // Ignore exclude, category, and category_name params if using include.186		$parsed_args['category']      = '';187		$parsed_args['category_name'] = '';188 189		$inclinks = wp_parse_id_list( $parsed_args['include'] );190		if ( count( $inclinks ) ) {191			foreach ( $inclinks as $inclink ) {192				if ( empty( $inclusions ) ) {193					$inclusions = ' AND ( link_id = ' . $inclink . ' ';194				} else {195					$inclusions .= ' OR link_id = ' . $inclink . ' ';196				}197			}198		}199	}200	if ( ! empty( $inclusions ) ) {201		$inclusions .= ')';202	}203 204	$exclusions = '';205	if ( ! empty( $parsed_args['exclude'] ) ) {206		$exlinks = wp_parse_id_list( $parsed_args['exclude'] );207		if ( count( $exlinks ) ) {208			foreach ( $exlinks as $exlink ) {209				if ( empty( $exclusions ) ) {210					$exclusions = ' AND ( link_id <> ' . $exlink . ' ';211				} else {212					$exclusions .= ' AND link_id <> ' . $exlink . ' ';213				}214			}215		}

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 7.1.0 tag, from src/wp-includes/bookmark.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.