Data Retrieval Functions

get_bookmark()

Retrieves bookmark data by ID or object.

get_bookmark( $bookmark, $output = OBJECT, $filter = 'raw' )

Parameters:

Returns: array|object|null — Bookmark data or null if not found.

Example:

// Get bookmark as object
$link = get_bookmark( 42 );
echo $link->link_name;
echo $link->link_url;

// Get as associative array
$link = get_bookmark( 42, ARRAY_A );
echo $link['link_name'];

// Get as numeric array
$link = get_bookmark( 42, ARRAY_N );
echo $link[0]; // link_id

Notes:

• Uses object cache (bookmark cache group)
• Falls back to global $link if no ID provided
• Retrieves link_category as array of term IDs

get_bookmark_field()

Retrieves a single field from a bookmark.

get_bookmark_field( $field, $bookmark, $context = 'display' )

Parameters:

Returns: string|WP_Error — Field value or error.

Example:

$url = get_bookmark_field( 'link_url', 42 );
$name = get_bookmark_field( 'link_name', 42 );
$desc = get_bookmark_field( 'link_description', 42, 'edit' );

Available Fields:

• link_id — Bookmark ID (int)
• link_url — URL
• link_name — Display name
• link_image — Image URL
• link_target — Target attribute (_blank, _top)
• link_category — Array of category IDs
• link_description — Description text
• link_visible — Visibility (Y or N)
• link_owner — Owner user ID (int)
• link_rating — Rating (int)
• link_updated — Last updated timestamp
• link_rel — Rel attribute (XFN)
• link_notes — Private notes
• link_rss — RSS feed URL

get_bookmarks()

Retrieves a list of bookmarks matching criteria.

get_bookmarks( $args = '' )

Parameters (as array):

Orderby Options:

• id / link_id — By ID
• name / link_name — By name (default)
• url / link_url — By URL
• visible / link_visible — By visibility
• rating / link_rating — By rating
• owner / link_owner — By owner
• updated / link_updated — By update time
• notes / link_notes — By notes
• description / link_description — By description
• length — By character length of name
• rand — Random order (disables caching)

Returns: object[] — Array of bookmark objects.

Examples:

// Get all bookmarks
$bookmarks = get_bookmarks();

// Get bookmarks from category 5, ordered by rating
$bookmarks = get_bookmarks( array(
    'category' => 5,
    'orderby' => 'rating',
    'order' => 'DESC',
) );

// Search bookmarks
$bookmarks = get_bookmarks( array(
    'search' => 'wordpress',
) );

// Get specific bookmarks
$bookmarks = get_bookmarks( array(
    'include' => '1,5,10',
) );

// Exclude certain bookmarks
$bookmarks = get_bookmarks( array(
    'exclude' => '3,7',
    'limit' => 10,
) );

Notes:

• Results are cached (except when orderby='rand')
• When include is set, exclude, category, and category_name are ignored
• The category_name parameter looks up the category by name and converts to ID

Template Functions

wp_list_bookmarks()

Outputs or returns HTML list of bookmarks, optionally grouped by category.

wp_list_bookmarks( $args = '' )

Parameters (as array):

Returns: void|string — Void if echo=1, HTML string if echo=0.

Examples:

// Basic blogroll in sidebar
wp_list_bookmarks();

// Custom styled blogroll
wp_list_bookmarks( array(
    'title_li' => 'Friends & Resources',
    'title_before' => '<h3 class="widget-title">',
    'title_after' => '</h3>',
    'categorize' => false,
    'show_description' => true,
    'between' => ' - ',
) );

// Get HTML without echoing
$html = wp_list_bookmarks( array(
    'echo' => false,
    'category' => 5,
) );

// Multiple categories, custom order
wp_list_bookmarks( array(
    'category' => '2,5,8',
    'orderby' => 'rating',
    'order' => 'DESC',
    'show_rating' => true,
) );

// Flat list (no category grouping)
wp_list_bookmarks( array(
    'categorize' => false,
    'title_li' => '',
    'before' => '',
    'after' => '<br />',
) );

Output Structure (categorized):

<li id="linkcat-2" class="linkcat">
  <h2>Category Name</h2>
  <ul class='xoxo blogroll'>
    <li><a href="http://example.com" title="Description">Link Name</a></li>
    <li><a href="http://example2.com">Another Link</a></li>
  </ul>
</li>

_walk_bookmarks()

Private function — Formats bookmark objects into HTML list items.

_walk_bookmarks( $bookmarks, $args = '' )

Note: This is an internal function used by wp_list_bookmarks(). Theme developers should use wp_list_bookmarks() instead.

Sanitization Functions

sanitize_bookmark()

Sanitizes all fields of a bookmark.

sanitize_bookmark( $bookmark, $context = 'display' )

Parameters:

Returns: stdClass|array — Sanitized bookmark (same type as input).

sanitize_bookmark_field()

Sanitizes a single bookmark field.

sanitize_bookmark_field( $field, $value, $bookmark_id, $context )

Parameters:

Returns: mixed — Sanitized value.

Context Behaviors:

Field-Specific Rules:

• link_id, link_rating — Cast to integer
• link_category — Cast to array of integers, returned immediately (no filters)
• link_visible — Only allows Y, N, y, n
• link_target — Only allows _top, _blank, or empty

Cache Functions

clean_bookmark_cache()

Clears all caches related to a bookmark.

clean_bookmark_cache( $bookmark_id )

Parameters:

Returns: void

Clears:

• Individual bookmark cache (bookmark group)
• get_bookmarks result cache
• Object term cache for the bookmark

Example:

// After manually updating a bookmark
$wpdb->update( $wpdb->links, $data, array( 'link_id' => 42 ) );
clean_bookmark_cache( 42 );