WordPress常用函数-wpdb 类

[管理员管理员 @admin]

WordPress为用户提供了一系列用于数据库操作的函数类——wpdb。Wpdb类建立在Justin Vincent 编写并维护的ezSQL 类的基础上。

使用须知
不可直接调用wpdb类中的方法，应使用全局变量$wpdb。$wpdb是WordPress提供的一个全局变量，该全局变量是负责与WordPress数据库交流的类的实例化。（在自定义函数中使用$wpdb前，请记住全局化$wpdb。）
例如在引用页面加上：
1.  global $wpdb;

可以用$wpdb对象从任何一个WordPress数据库表（而非仅仅标准数据库表）中读取数据。例如，如果你需要从一个名为“mytable”的自定义表中选定一些信息，可以使用以下代码：
1.  $myrows = $wpdb->get_results( "SELECT id, name FROM mytable" );

$wpdb对象可以与任何数量的数据库表交流，但这些数据库表只能来自一个数据库——WordPress数据库。如果你要连接到其它数据库（极少情况），那么你就需要用相应的连接细节信息从wpdb类中将你的对象实例化。如果需要设置多个数据库，可以考虑使用 hyperdb 。

执行数据库查询
你可以通过query函数在WordPress数据库中执行任何SQL查询。不过我们推荐为SELECT查询使用更为具体的函数。
1.  <?php $wpdb->query('query'); ?>

query（字符串）你希望执行的SQL语句。

函数返回一个与选定内容的行数相应的整数。如果发生MySQL错误，函数返回FALSE。（注意：0和FALSE都可能被返回，确保使用正确的比较运算符：equality == vs. identicality ===）。

注意：使用wpdb类中所有可执行SQL查询的函数时，都需要将所有输入内容/inputs进行字符转义（如wpdb->escape($user_entered_data_string)）。见下文。

示例
删除ID为13的文章的“gargle”元关键字和值。

 Code: arbitrary (select) 

1.
2.
3.

$wpdb->query("
DELETE FROM $wpdb->postmeta WHERE post_id = '13'
AND meta_key = 'gargle'");

由delete_post_meta 执行。
将页面 7设为页面15的父级。

 Code: arbitrary (select) 

1.
2.
3.

$wpdb->query("
UPDATE $wpdb->posts SET post_parent = 7
WHERE ID = 15 AND post_status = 'static'");

get_var函数
选择一个变量
get_var函数返回一个来自数据库的变量。虽然只返回一个变量，但查询结果会被整体缓存，供后期使用。如果没有查询结果，返回NULL。
1.  <?php $wpdb->get_var('query',column_offset,row_offset); ?>
query（字符串）你希望执行的查询。将该参数设为null会使函数返回上一个查询缓存结果中的具体变量。
column_offset（整数）预计的数据库表的列数（0为表中第一列）。默认值为0。
row_offset（整数）预计的数据库表的行数（0为表中第一行）。默认值为0。

示例
检索并返回用户数量。

 Code: arbitrary (select) 

1.
2.
3.
4.

<?php
$user_count = $wpdb->get_var($wpdb->prepare("SELECT COUNT(*) FROM $wpdb->users;"));
echo '<p>User count is ' . $user_count . '</p>';
?>

检索并返回自定义字段 值的总数。

 Code: arbitrary (select) 

1.
2.
3.
4.
5.

<?php
$meta_key = 'miles';//set this to appropriate custom field meta key
$allmiles=$wpdb->get_var($wpdb->prepare("SELECT sum(meta_value) FROM $wpdb->postmeta WHERE meta_key = %s", $meta_key));
echo '<p>Total miles is '.$allmiles . '</p>';
?>

get_row函数
选择表行
从某个查询中检索一整行内容，可使用get_row函数。该函数可将行作为对象、关联数组或数值索引数组返回。如果查询返回了多个行，函数只返回指定行，但所有返回的行都将被缓存以供日后使用。

1.  <?php $wpdb->get_row('query', output_type, row_offset); ?>

query （字符串）你希望执行的查询语句。
output_type 三个预定义的常量之一。默认值为OBJECT。
OBJECT —— 返回的结果以对象形式输出
ARRAY_A ——返回的结果以关联数组形式输出
ARRAY_N —— 返回的结果以数值索引数组形式输出
row_offset （整数）预计的数据库表的行数（0为表中第一行）。默认值为0。

示例
获取ID为10的链接的所有资料。
1.  $mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10");
$mylink对象的属性即SQL查询结果的行名称（在该例中，即 $wpdb->links表中的所有行）。

 Code: arbitrary (select) 

1.
2.

echo $mylink->link_id; // prints "10"  
$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_A);

则会生成一个关联数组：

 Code: arbitrary (select) 

1.
2.

echo $mylink['link_id']; // prints "10"  
$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_N);

则会生成一个数值索引数组：
1.  echo $mylink[1]; // prints "10"

get_col函数
选择表列
要选择数据库表中的一列内容，可使用get_col函数。该函数输出一个空间数组，如果查询返回了多个列，函数只返回指定列，但所有返回的列都将被缓存以供日后使用。

1.  <?php $wpdb->get_col('query',column_offset); ?>
query（字符串）你希望执行的查询。将该参数设为null会使函数返回上一个查询的缓存结果中的执行表列。
column_offset（整数）预计的数据库表的列数（0为表中第一列）。默认值为0。

示例
在这个例子中，我们假设有一个专注于发布汽车资讯的博客，博客中每篇文章都介绍了一辆特别的汽车（如1969 Ford Mustang）。此外我们将三个自定义字段 ——manufacture、model和year指定给各篇文章。这里我们的目的是显示manufacturer（生产商）为Ford的所有文章的标题，各个标题按模型和年份排列。

可以利用wpdb类的get_col形式返回一个符合要求、以正确顺序排列的文章ID数组。然后通过foreach构造函数重复该文章ID数组，显示每篇文章的标题。本示例的SQL查询由 Andomar编写。

 Code: arbitrary (select) 

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.

<?php
$meta_key1 = 'model';
$meta_key2 = 'year';
$meta_key3 = 'manufacturer';
$meta_key3_value = 'Ford';

$postids=$wpdb->get_col($wpdb->prepare("
SELECT key3.post_id
FROM $wpdb->postmeta key3
INNER JOIN $wpdb->postmeta key1
on key1.post_id = key3.post_id
and key1.meta_key = %s
INNER JOIN $wpdb->postmeta key2
on key2.post_id = key3.post_id
and key2.meta_key = %s
WHERE key3.meta_key = %s
and key3.meta_value = %s
ORDER BY key1.meta_value, key2.meta_value",$meta_key1, $meta_key2, $meta_key3, $meta_key3_value));

if ($postids) {
echo 'List of $meta_key3_value . '(s), sorted by ' . $meta_key1 . ', ' . $meta_key2;
foreach ($postids as $id) {
$post=get_post(intval($id));
setup_postdata($post);?>
<p><a href="<?php the_permalink() ? rel="nofollow">" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></p>
<?php
}
}
?>

get_results函数
选择生成的结果
get_results可以从数据库中抽取函数生成的多行结果。Wpdb函数以数组形式返回整个查询结果。数组中每个元素都对应查询结果中的一行，如get_row既可以是对象，也可以是关联数组或数值型数组。

1.  <?php $wpdb->get_results('query', output_type); ?>
query（字符串）你希望执行的查询语句。将该参数设为null会使函数返回上一个查询的缓存结果中的信息。
output_type三个预定义的常量之一。默认值为OBJECT。更多信息请见上文中的“选择表行”。
OBJECT —— 以对象形式输出返回的结果
ARRAY_A ——以关联数组形式输出返回的结果
ARRAY_N —— 以数值索引数组形式输出返回的结果

示例
获取ID为5的用户的所有文章草稿的ID和标题并回应标题。

 Code: arbitrary (select) 

1.
2.
3.
4.
5.
6.

$fivesdrafts = $wpdb->get_results("SELECT ID, post_title FROM $wpdb->posts
WHERE post_status = 'draft' AND post_author = 5");

foreach ($fivesdrafts as $fivesdraft) {
echo $fivesdraft->post_title;
}

获取ID为5的用户的所有文章草稿信息。

 Code: arbitrary (select) 

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.

<?php
$fivesdrafts = $wpdb->get_results("SELECT * FROM $wpdb->posts
WHERE post_status = 'draft' AND post_author = 5");
if ($fivesdrafts) :
foreach ($fivesdrafts as $post) :
setup_postdata($post);
?>
<h2><a href="<?php the_permalink(); ? rel="nofollow">" rel="bookmark"
title="Permanent Link to <?php the_title(); ?>"><?php the_title(); ?></a></h2>
<?php
endforeach;
else :
?>
<h2> Not Found</h2>
<?php endif; ?>

插入表行/列
在数据库表中插入一行/列内容。

示例
在一行中插入两列内容，第一个列的值为字符串，第二列的值为数字：
1.  $wpdb->insert( 'table', array( 'column1' => 'value1', 'column2' => 123 ), array( '%s', '%d' ) )
可能的值：- %s 为字符串，- %d 为十进制数字，- %f 为浮点。

更新表行/列
更新数据库表中某行/列的内容。

示例
要更新一个表行，其ID为1，该行第一列中的值是一个字符串，第二列中的值是一个数字：
1.  $wpdb->update( 'table', array( 'column1' => 'value1', 'column2' => 'value2' ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
防止数据库查询遭到SQL 注入式攻击

更多在WordPress中避免SQL攻击的信息，请看数据验证 。这是WordPress代码编写者和插件开发者的必读文章。
简单地说，执行SQL查询以阻止SQL注入式攻击前，SQL查询中的所有数据都需要经过SQL字符转义。可以通过prepare方法快速完成字符转义，该方法使用 sprintf() -like语句。

1.  <?php $sql = $wpdb->prepare( 'query'[, value_parameter, value_parameter ... ] ); ?>
query（字符串）你希望执行的SQL查询，以 %s 与%d作为占位符。
value_parameter（字符串）提交到占位符中的值。该值此时必须没有被SQL转义。

示例
将Meta key => value pair “Harriet’s Adages” => “WordPress’ database interface is like Sunday Morning: Easy.”添加到ID为10的文章。

 Code: arbitrary (select) 

1.
2.
3.
4.
5.
6.
7.
8.

$metakey = "Harriet's Adages";
$metavalue = "WordPress' database interface is like Sunday Morning: Easy.";

$wpdb->query( $wpdb->prepare( "
INSERT INTO $wpdb->postmeta
( post_id, meta_key, meta_value )
VALUES ( %d, %s, %s )",
10, $metakey, $metavalue ) );

由add_meta()执行。

注意，这时你无须担心引用字符串。不要直接将变量传递给SQL查询，可将 %s作为字符串的占位符， %d作为整数的占位符。你可以传递任意个值，每一个都可以作为prepare()方法的新参数。

显示/隐藏SQL 错误

你可以用show_errors来显示SQL错误，也可以用hide_errors隐藏SQL错误。

 Code: arbitrary (select) 

1.
2.

<?php $wpdb->show_errors(); ?>
<?php $wpdb->hide_errors(); ?>

同样也可以用print_error输出近期的查询所生成的错误。

1.  <?php $wpdb->print_error(); ?>

get_col_info函数
获取数据库表中某列信息
利用get_col_info可以检索到近期查询的表列信息。当你不了解某个函数返回的对象的属性时，就可以通过get_col_info函数获取信息。该函数从指定列中输出所需信息，如果没有指定某列，则函数输出一个以查询结果中所有列的信息为内容的数组。

1.  <?php $wpdb->get_col_info('type', offset); ?>

type（字符串）你希望检索的信息。可能为以下任何值之一（摘自 ezSQL 文档）。默认值为name。
name ——表列的名称。默认值
table ——列所属表格的表格名称
max_length —— 表列的最大长度
not_null —— 若表列不为Null则值为1
primary_key —— 若表列是一个主键，值为1
unique_key —— 若表列是唯一键，值为1
multiple_key —— 若表列是非唯一键，值为1
numeric —— 若表列是数值型，值为1
blob —— 若表列为BLOB，值为1
type —— 表列的类型
unsigned —— 若表列无符号，值为1
zerofill —— 若表列为zero-filled，值为1
offset
（整数）从某个检索信息的表中指定表列（0为表中第一列）。默认值为-1。
-1 —— 从所有表列中检索信息。输出一个数组。默认值。
非负整数 —— 从指定的表列中检索信息（0为表中第一列）。

flush()函数
用flush清除SQL结果缓存。
1.  <?php $wpdb->flush(); ?>
这会清除$wpdb->last_result、$wpdb->last_query以及$wpdb->col_info信息。

类变量
$show_errors
是否显示SQL错误信息。默认为TRUE。

$num_queries
已经被执行的查询次数

$last_query
最近一次已经被执行的查询

$queries
将SAVEQUERIES常量设为TRUE（该常量默认值为FALSE），可以保存所有数据库查询及其停止时间。如果SAVEQUERIES值为TRUE，你的查询会被作为数组保存在$queries变量中。

$last_result
最近一次查询结果。

$col_info
最近一次查询结果的表列信息。参见获取表列信息。

$insert_id
最近一次INSERT查询为AUTO_INCREMENT列生成的ID。

$num_rows
最近一次查询返回的行数。

表
在wpdb类中可以引用WordPress数据库表。

$posts
关于文章的数据库表

$users
关于用户的数据库表

$comments
评论表

$links
链接表

$options
选项表

$postmeta
元数据（自定义字段）表

$usermate
usermeta表中含有用户的其它信息，如昵称、个人说明与权限。

$terms
terms表中包括对分类目录、链接分类、标签的“说明”（description）

$term_taxonomy
term_taxonomy表介绍了WordPress的不同分类（taxonomy）。分类目录、链接分类、标签都是一种分类。

$term_relationships
term_relationships表中含有术语以及使用术语的对象之间的链接，即该表可以指向日志所属的分类目录。

[作者]

帖子