README

基于 Laravel 的 Query Builder 的 WordPress 表达式查询构建器。包装了全局的 $wpdb。

如何在托管环境中使用

如果您希望在托管环境中使用此扩展，请使用 composer 进行安装

composer require stephenharris/wp-query-builder

如何使用查询构建器

include('vendor/autoload.php');

global $wpdb;
$qb = new WPQueryBuilder\Query($wpdb);

如何在分布式插件中使用

由于无法管理插件之间的依赖关系，将此库捆绑到插件中可能会造成错误（可能是致命错误），如果与包含它的另一个插件一起使用。

在您的插件中捆绑此库的安全方式是使用 Mozart。这会复制代码库，但将其包装在自定义命名空间中。

您需要处理库类的自动加载。它们可以根据 PSR-4 从 Mozart 目标目录进行自动加载。

global $wpdb;
$qb = new YourPluginNameSpace\WPQueryBuilder\Query($wpdb);

数据净化

此库的目的是提供一个 表达式 和 安全 的方法来运行针对您的 WordPress 数据库的查询（通常涉及自定义表）。

为此，所有提供的 值 都已转义，但请注意，列和表 名称尚未转义。无论如何，即使它们已转义，您也应将任何允许的列/表列入白名单：否则，使用用户输入或其他不受信任的数据确定列/表可能会允许攻击者检索他们不应检索的数据或生成您的数据库映射。

查询结果

检索表中的所有行

$qb->select()->from("wp_users")->get();
//SELECT * FROM wp_users;

检索单行

$qb->select()->from("wp_users")->where("user_email", "=", "admin@example.com")->first();
//SELECT * FROM wp_users WHERE user_email = 'admin@example.com' LIMIT 1;

检索单列

要检索返回结果中的第一列

$usernames = $qb->select(["user_login", "user_email"])->from("wp_users")->getColumn();

要检索特定列

$emails = $qb->select(["user_login", "user_email"])->from("wp_users")->getColumn("user_email");

要检索值

$email = $qb->select("user_email")->from("wp_users")->where("ID", "=", 123)->getScalar();

基本 WHERE 子句

添加 WHERE 子句，匹配列值等于/不等于/大于/小于/大于等于/小于等于 (=/, !=, >, <, >=, <=) 的记录；

$qb->select()
    ->from("wp_posts")
    ->where("post_status", "=", "publish")
		->andWhere("post_date", ">=", "2018-05-31 10:00:00")
		->get();
//SELECT * FROM wp_posts WHERE post_status='publish' AND post_date >= "2018-05-31 10:00:00";

要添加 OR 条件，请使用 orWhere($column, $operator, $value)。

WHERE 列值 IN

添加 WHERE 子句，匹配具有提供的数组中列值的记录

$qb->select()->from("wp_users")->whereIn("ID", [1, 2, 3])->get();
//SELECT * FROM wp_users WHERE ID IN (1, 2, 3);

WHERE 列值 IN

添加 WHERE 子句，匹配具有提供的数组中列值的记录

$qb->select()->from("wp_users")->whereIn("ID", [1, 2, 3])->get();
//SELECT * FROM wp_users WHERE ID IN (1, 2, 3);

WHERE 列值 BETWEEN

添加 WHERE 子句，匹配具有两个指定值之间的列值的记录

$qb->select()->from("wp_posts")->whereBetween("post_date", '2018-05-01 00:00:00', '2018-05-31 23:59:59')->get();
//SELECT * FROM wp_posts BETWEEN '2018-05-01 00:00:00' AND '2018-05-31 23:59:59';

搜索字段

在一个或多个字段上执行 LIKE 比较。

$qb->select()->from("wp_posts")->search("post_title", "foo")->get();
//SELECT * FROM wp_posts WHERE post_title='%foo%';

要搜索多个列，可以传递列数组

$qb->select()->from("wp_posts")->search(["post_title", "post_content", "post_excerpt"], "foo")->get();
//SELECT * FROM wp_posts WHERE post_title='%foo%' OR post_content='%foo%' OR post_excerpt='%foo%';

复杂的 WHERE 子句

andWhere（及其别名 where）和 orWhere 都接受 WhereCause 实例。这允许您构建更复杂的查询，例如嵌套的 WHERE 条件。

$privateAndAuthor = new WPQueryBuilder\CompositeWhereClause();
$privateAndAuthor->andWhere(new WPQueryBuilder\BasicWhereClause('post_status', '==', 'private'))
$privateAndAuthor->andWhere(new WPQueryBuilder\BasicWhereClause('post_author', '==', 1));

$qb->select()
	->from("wp_posts")
	->where($privateAndAuthor)
	->orWhere("post_status", '=', "publish")
	->get();

//SELECT * FROM wp_posts WHERE (post_status = 'private' AND  post_author = 1) OR post_status = 'publish';

连接

有四种连接方法

$query->select(['wp_posts.*', 'u.user_nicename'])
 ->('wp_posts')
 ->leftJoin('wp_users as u', 'wp_posts.post_author', '=', 'u.ID');

// SELECT wp_posts.*, u.user_nicename FROM wp_posts LEFT JOIN wp_users as u ON wp_posts.post_author = u.ID;

方法

• leftJoin($table, $firstColumn, $operator, $secondColumn)
• rightJoin($table, $firstColumn, $operator, $secondColumn)
• innerJoin($table, $firstColumn, $operator, $secondColumn)
• fullJoin($table, $firstColumn, $operator, $secondColumn)

插入记录

Query::insert 方法将使用给定的列/值（给定一个数组，其中列是键）插入一条记录。您必须使用 Query::table 与指定的表名调用。

$qb->table("wp_posts")
	->insert(
		"post_title" => "My Post Title",
		"post_content" => "My post content...",
		"post_status" => "publish",
	);

// INSERT INTO wp_posts (post_title, post_content, post_status) VALUES ('My Post Title', 'My post content...', 'publish');

删除记录

Query::delete 方法将通过 Query::table 或 Query::from 命令执行指定表的删除命令。必须在任何 WHERE 条件之后调用 delete 方法，否则将删除整个表。

$qb->table("wp_posts")
	->where("ID", "=", 123)
	->delete();

// DELETE FROM wp_posts WHERE ID='123';

错误处理

错误地调用方法（例如，在没有先调用 Query::table 的情况下调用 Query::get，或将未包含在查询结果中的字段传递给 getColumn），将导致抛出 LogicException（可能是 BadMethodCallException 或 InvalidArgumentException）。

如果 SQL 查询失败，则抛出 WPQueryBuilder(QueryException。

try {
	$qb->set([
			'ID' => 5,
			'post_title' => 'Updating a post'
   	])
	 	->where('ID', '=', 3)
	 	->update();
} catch (\LogicException $e) {

	// There is an error in your code

} catch (\WPQueryBuilder\QueryException $e) {

	// This could be data conflict

}