云策 WordPress 开发者社区

函数文档

get_posts_by_author_sql()

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

概述

get_posts_by_author_sql() 函数用于基于用户权限、作者和文章类型生成 SQL WHERE 子句，以筛选文章。它返回一个标准化的 SQL 代码片段，可添加到查询中，确保正确处理公开和私有文章的访问权限。

关键要点

  • 函数根据 $post_type、$full、$post_author 和 $public_only 参数构建 SQL WHERE 子句。
  • 支持单个或数组形式的文章类型，并检查用户是否有读取私有文章的权限。
  • 返回的 SQL 包含文章类型、状态（如 publish 或 private）和作者条件，$full 参数控制是否包含 'WHERE' 关键字。
  • 使用 apply_filters_deprecated() 钩子过滤权限，但自 3.2.0 版本后已弃用。
  • 相关函数包括 current_user_can()、is_user_logged_in() 等，用于权限和用户状态检查。

代码示例

$where = get_posts_by_author_sql( 'post' );
echo $where;

// 用户登录时输出: WHERE post_type = 'post' AND (post_status = 'publish' OR post_status = 'private')
// 用户未登录时输出: WHERE post_type = 'post' AND (post_status = 'publish')

// 查询标题为 "Hello world!" 的文章 ID
global $wpdb;
$query = "SELECT ID FROM $wpdb->posts $where AND post_title = %s";
$post_id = $wpdb->get_var( $wpdb->prepare( $query, 'Hello world!' ) );

注意事项

  • $full 参数设置为 false 时可能不会返回预期的文章过滤器，需参考相关补丁和测试（如 WordPress Trac 工单 #30354）。
  • 自 4.3.0 版本起，$post_type 参数支持数组形式；函数最初在 3.0.0 版本引入。
  • pub_priv_sql_capability 过滤器已弃用，建议直接使用 current_user_can() 进行权限检查。
📄 原文内容

Retrieves the post SQL based on capability, author, and type.

Description

See also

Parameters

$post_typestring|string[]required
Single post type or an array of post types.
$fullbooloptional
Returns a full WHERE statement instead of just an 'andalso' term.

Default:true

$post_authorintoptional
Query posts having a single author ID.

Default:null

$public_onlybooloptional
Only return public posts. Skips cap checks for $current_user.

Default:false

Return

string SQL WHERE code that can be added to a query.

More Information

This function provides a standardized way to appropriately select on the post_status of a post type. The function will return a piece of SQL code that can be added to a WHERE clause; this SQL is constructed to allow all published posts, and all private posts to which the user has access.

Source

function get_posts_by_author_sql( $post_type, $full = true, $post_author = null, $public_only = false ) {
	global $wpdb;

	if ( is_array( $post_type ) ) {
		$post_types = $post_type;
	} else {
		$post_types = array( $post_type );
	}

	$post_type_clauses = array();
	foreach ( $post_types as $post_type ) {
		$post_type_obj = get_post_type_object( $post_type );

		if ( ! $post_type_obj ) {
			continue;
		}

		/**
		 * Filters the capability to read private posts for a custom post type
		 * when generating SQL for getting posts by author.
		 *
		 * @since 2.2.0
		 * @deprecated 3.2.0 The hook transitioned from "somewhat useless" to "totally useless".
		 *
		 * @param string $cap Capability.
		 */
		$cap = apply_filters_deprecated( 'pub_priv_sql_capability', array( '' ), '3.2.0' );

		if ( ! $cap ) {
			$cap = current_user_can( $post_type_obj->cap->read_private_posts );
		}

		// Only need to check the cap if $public_only is false.
		$post_status_sql = "post_status = 'publish'";

		if ( false === $public_only ) {
			if ( $cap ) {
				// Does the user have the capability to view private posts? Guess so.
				$post_status_sql .= " OR post_status = 'private'";
			} elseif ( is_user_logged_in() ) {
				// Users can view their own private posts.
				$id = get_current_user_id();
				if ( null === $post_author || ! $full ) {
					$post_status_sql .= " OR post_status = 'private' AND post_author = $id";
				} elseif ( $id === (int) $post_author ) {
					$post_status_sql .= " OR post_status = 'private'";
				} // Else none.
			} // Else none.
		}

		$post_type_clauses[] = "( post_type = '" . $post_type . "' AND ( $post_status_sql ) )";
	}

	if ( empty( $post_type_clauses ) ) {
		return $full ? 'WHERE 1 = 0' : '1 = 0';
	}

	$sql = '( ' . implode( ' OR ', $post_type_clauses ) . ' )';

	if ( null !== $post_author ) {
		$sql .= $wpdb->prepare( ' AND post_author = %d', $post_author );
	}

	if ( $full ) {
		$sql = 'WHERE ' . $sql;
	}

	return $sql;
}

View all references View on Trac View on GitHub

Hooks

apply_filters_deprecated( ‘pub_priv_sql_capability’, string $cap )

Filters the capability to read private posts for a custom post type when generating SQL for getting posts by author.

Uses Description
apply_filters_deprecated()wp-includes/plugin.php

Fires functions attached to a deprecated filter hook.
current_user_can()wp-includes/capabilities.php

Returns whether the current user has the specified capability.
is_user_logged_in()wp-includes/pluggable.php

Determines whether the current visitor is a logged in user.
get_current_user_id()wp-includes/user.php

Gets the current user’s ID.
get_post_type_object()wp-includes/post.php

Retrieves a post type object by name.
wpdb::prepare()wp-includes/class-wpdb.php

Prepares a SQL query for safe execution.

Show 4 moreShow less

Used by Description
WP_User_Query::parse_orderby()wp-includes/class-wp-user-query.php

Parses and sanitizes ‘orderby’ keys passed to the user query.
count_user_posts()wp-includes/user.php

Gets the number of posts a user has written.
count_many_users_posts()wp-includes/user.php

Gets the number of posts written by a list of users.
get_private_posts_cap_sql()wp-includes/post.php

Retrieves the private post SQL based on capability.

Changelog

Version Description
4.3.0 Introduced the ability to pass an array of post types to $post_type.
3.0.0 Introduced.

User Contributed Notes

  2. Skip to note 4 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Example

    $where = get_posts_by_author_sql( 'post' );
echo $where;

// user logged in: WHERE post_type = 'post' AND (post_status = 'publish' OR post_status = 'private')
// user not logged in: WHERE post_type = 'post' AND (post_status = 'publish')

// get post ID with title "Hello world!" query
global $wpdb;
$query = "SELECT ID FROM $wpdb->posts $where AND post_title = %s";
$post_id = $wpdb->get_var( $wpdb->prepare( $query, 'Hello world!' ) );