云策 WordPress 开发者社区

函数文档

get_bookmark()

查看官方原文 ↗
💡 云策文档标注

概述

get_bookmark() 函数用于从 WordPress 数据库中检索书签（链接）数据，支持多种返回格式和过滤选项。它通过参数控制输出类型，并利用缓存机制优化性能。

关键要点

  • 函数签名：get_bookmark( $bookmark, $output = OBJECT, $filter = 'raw' )
  • 参数 $bookmark 可以是整数（书签 ID）或 stdClass 对象，必需；$output 可选，指定返回类型（OBJECT、ARRAY_A 或 ARRAY_N），默认 OBJECT；$filter 可选，控制字段清理方式，默认 'raw'
  • 返回类型取决于 $output 参数，可能为对象、数组或 null
  • 内部实现包括缓存检查（wp_cache_get/wp_cache_add）、数据库查询（wpdb::get_row）和清理（sanitize_bookmark）
  • 相关函数包括 wp_get_object_terms 用于获取关联分类，以及多个使用此函数的其他 WordPress 核心函数

代码示例

// 示例：获取书签并显示名称
$bookmark = get_bookmark( 1 ); // 假设 ID 为 1
if ( $bookmark ) {
    echo $bookmark->link_name;
}

// 示例：将书签作为链接输出
$bookmark = get_bookmark( 1 );
if ( $bookmark ) {
    echo '<a href="' . $bookmark->link_url . '">' . $bookmark->link_name . '</a>';
}

注意事项

  • 函数自 WordPress 2.1.0 版本引入，兼容性良好
  • 如果 $bookmark 为空且全局 $link 存在，则使用全局变量；否则返回 null
  • 输出类型需准确指定以避免数据类型错误，例如 ARRAY_A 返回关联数组，ARRAY_N 返回数值数组
  • 使用 $filter 参数可以控制数据清理级别，确保安全性
📄 原文内容

Retrieves bookmark data.

Parameters

$bookmarkint|stdClassrequired
$outputstringoptional
The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to an stdClass object, an associative array, or a numeric array, respectively.

Default:OBJECT

$filterstringoptional
How to sanitize bookmark fields. Default 'raw'.

Return

array|object|null Type returned depends on $output value.

Source

function get_bookmark( $bookmark, $output = OBJECT, $filter = 'raw' ) {
	global $wpdb;

	if ( empty( $bookmark ) ) {
		if ( isset( $GLOBALS['link'] ) ) {
			$_bookmark = & $GLOBALS['link'];
		} else {
			$_bookmark = null;
		}
	} elseif ( is_object( $bookmark ) ) {
		wp_cache_add( $bookmark->link_id, $bookmark, 'bookmark' );
		$_bookmark = $bookmark;
	} else {
		if ( isset( $GLOBALS['link'] ) && ( $GLOBALS['link']->link_id === $bookmark ) ) {
			$_bookmark = & $GLOBALS['link'];
		} else {
			$_bookmark = wp_cache_get( $bookmark, 'bookmark' );
			if ( ! $_bookmark ) {
				$_bookmark = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->links WHERE link_id = %d LIMIT 1", $bookmark ) );
				if ( $_bookmark ) {
					$_bookmark->link_category = array_unique( wp_get_object_terms( $_bookmark->link_id, 'link_category', array( 'fields' => 'ids' ) ) );
					wp_cache_add( $_bookmark->link_id, $_bookmark, 'bookmark' );
				}
			}
		}
	}

	if ( ! $_bookmark ) {
		return $_bookmark;
	}

	$_bookmark = sanitize_bookmark( $_bookmark, $filter );

	if ( OBJECT === $output ) {
		return $_bookmark;
	} elseif ( ARRAY_A === $output ) {
		return get_object_vars( $_bookmark );
	} elseif ( ARRAY_N === $output ) {
		return array_values( get_object_vars( $_bookmark ) );
	} else {
		return $_bookmark;
	}
}

View all references View on Trac View on GitHub

Uses Description
wp_cache_add()wp-includes/cache.php

Adds data to the cache, if the cache key doesn’t already exist.
wp_get_object_terms()wp-includes/taxonomy.php

Retrieves the terms associated with the given object(s), in the supplied taxonomies.
sanitize_bookmark()wp-includes/bookmark.php

Sanitizes all bookmark fields.
wpdb::get_row()wp-includes/class-wpdb.php

Retrieves one row from the database.
wp_cache_get()wp-includes/cache.php

Retrieves the cache contents from the cache by key and group.
wpdb::prepare()wp-includes/class-wpdb.php

Prepares a SQL query for safe execution.

Show 2 moreShow less

Used by Description
wp_ajax_delete_link()wp-admin/includes/ajax-actions.php

Handles deleting a link via AJAX.
get_link_to_edit()wp-admin/includes/bookmark.php

Retrieves link data based on its ID.
wp_update_link()wp-admin/includes/bookmark.php

Updates a link in the database.
get_link()wp-includes/deprecated.php

Retrieves bookmark data based on ID.
get_edit_bookmark_link()wp-includes/link-template.php

Displays the edit bookmark link.
edit_bookmark_link()wp-includes/link-template.php

Displays the edit bookmark link anchor content.
get_bookmark_field()wp-includes/bookmark.php

Retrieves single bookmark data item or field.

Show 2 moreShow less

Changelog

Version Description
2.1.0 Introduced.

User Contributed Notes