云策 WordPress 开发者社区

函数文档

wp_count_posts()

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

概述

wp_count_posts() 函数用于高效统计指定文章类型的文章数量，并考虑用户权限（如可读性）。它返回一个包含各状态文章数量的对象，适用于 WordPress 2.5 及以上版本，替代了 get_posts() 等开销较大的方法。

关键要点

  • 函数返回一个 stdClass 对象，属性为文章状态（如 publish、draft）及其对应数量
  • 参数 $type 指定文章类型，默认为 'post'；$perm 可选 'readable' 以检查用户读取私有文章的权限
  • 使用缓存机制（wp_cache_get/set）提升性能，并应用 wp_count_posts 过滤器
  • 内部根据权限条件优化 SQL 查询，利用数据库索引
  • 相关函数包括 post_type_exists()、get_post_stati()、current_user_can() 等

代码示例

// 获取已发布文章数量
$count_posts = wp_count_posts();
if ( $count_posts ) {
    $published_posts = $count_posts->publish;
}

// 仅 PHP5+ 的简写方式
$published_posts = wp_count_posts()->publish;

// 统计页面数量
$count_pages = wp_count_posts( 'page' );

注意事项

  • 如果文章类型不存在，函数返回空对象
  • 默认情况下，$perm 参数为空，不检查权限；设为 'readable' 时，会根据当前用户能力调整私有文章统计
  • 对象属性包括所有注册的文章状态，未出现的状态计为 0
📄 原文内容

Counts number of posts of a post type and if user has permissions to view.

Description

This function provides an efficient method of finding the amount of post’s type a blog has. Another method is to count the amount of items in get_posts() , but that method has a lot of overhead with doing so. Therefore, when developing for 2.5+, use this function instead.

The $perm parameter checks for ‘readable’ value and if the user can read private posts, it will display that for the user that is signed in.

Parameters

$typestringoptional
Post type to retrieve count. Default 'post'.
$permstringoptional
'readable' or empty. Default empty.

Return

stdClass An object containing the number of posts for each status, or an empty object if the post type does not exist.

Source

function wp_count_posts( $type = 'post', $perm = '' ) {
	global $wpdb;

	if ( ! post_type_exists( $type ) ) {
		return new stdClass();
	}

	$cache_key = _count_posts_cache_key( $type, $perm );

	$counts = wp_cache_get( $cache_key, 'counts' );
	if ( false !== $counts ) {
		// We may have cached this before every status was registered.
		foreach ( get_post_stati() as $status ) {
			if ( ! isset( $counts->{$status} ) ) {
				$counts->{$status} = 0;
			}
		}

		/** This filter is documented in wp-includes/post.php */
		return apply_filters( 'wp_count_posts', $counts, $type, $perm );
	}

	if (
		'readable' === $perm &&
		is_user_logged_in() &&
		! current_user_can( get_post_type_object( $type )->cap->read_private_posts )
	) {
		// Optimized query uses subqueries which can leverage DB indexes for better performance. See #61097.
		$query = "
			SELECT post_status, COUNT(*) AS num_posts
			FROM (
				SELECT post_status
				FROM {$wpdb->posts}
				WHERE post_type = %s AND post_status != 'private'
				UNION ALL
				SELECT post_status
				FROM {$wpdb->posts}
				WHERE post_type = %s AND post_status = 'private' AND post_author = %d
			) AS filtered_posts
		";
		$args  = array( $type, $type, get_current_user_id() );
	} else {
		$query = "
			SELECT post_status, COUNT(*) AS num_posts
			FROM {$wpdb->posts}
			WHERE post_type = %s
		";
		$args  = array( $type );
	}

	$query .= ' GROUP BY post_status';

	$results = (array) $wpdb->get_results(
		$wpdb->prepare( $query, ...$args ), // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- Placeholders are used in the string contained in the variable.
		ARRAY_A
	);
	$counts  = array_fill_keys( get_post_stati(), 0 );

	foreach ( $results as $row ) {
		$counts[ $row['post_status'] ] = $row['num_posts'];
	}

	$counts = (object) $counts;
	wp_cache_set( $cache_key, $counts, 'counts' );

	/**
	 * Filters the post counts by status for the current post type.
	 *
	 * @since 3.7.0
	 *
	 * @param stdClass $counts An object containing the current post_type's post
	 *                         counts by status.
	 * @param string   $type   Post type.
	 * @param string   $perm   The permission to determine if the posts are 'readable'
	 *                         by the current user.
	 */
	return apply_filters( 'wp_count_posts', $counts, $type, $perm );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_count_posts’, stdClass $counts, string $type, string $perm )

Filters the post counts by status for the current post type.

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

Saves the data to the cache.
_count_posts_cache_key()wp-includes/post.php

Returns the cache key for wp_count_posts() based on the passed arguments.
post_type_exists()wp-includes/post.php

Determines whether a post type is registered.
get_post_stati()wp-includes/post.php

Gets a list of post statuses.
current_user_can()wp-includes/capabilities.php

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

Retrieves the cache contents from the cache by key and group.
is_user_logged_in()wp-includes/pluggable.php

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

Calls the callback functions that have been added to a filter hook.
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::get_results()wp-includes/class-wpdb.php

Retrieves an entire SQL result set from the database (i.e., many rows).
wpdb::prepare()wp-includes/class-wpdb.php

Prepares a SQL query for safe execution.

Show 8 moreShow less

Used by Description
wp_dashboard_right_now()wp-admin/includes/dashboard.php

Dashboard widget that displays some basic stats about the site.
get_available_post_statuses()wp-admin/includes/post.php

Returns all the possible statuses for a post type.
WP_Posts_List_Table::get_views()wp-admin/includes/class-wp-posts-list-table.php
WP_Posts_List_Table::prepare_items()wp-admin/includes/class-wp-posts-list-table.php

Changelog

Version Description
2.5.0 Introduced.

User Contributed Notes

  1. Skip to note 7 content


    Codex


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

    Get the Publish Status Post Count

    To get the published status type, you would call the wp_count_posts() function and then access the ‘publish’ property.

    $count_posts = wp_count_posts();

if ( $count_posts ) {
	$published_posts = $count_posts->publish;
}

    If you are developing for PHP5 only, then you can use shorthand, if you only want to get one status. This will not work in PHP4 and if you want to maintain backwards compatibility, then you must use the above code.

    $published_posts = wp_count_posts()->publish;

  2. Skip to note 8 content


    Mike Ritter


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

    This function returns an object whose properties you can access:

     stdClass Object ( [publish] => 12 [future] => 0 [draft] => 0 [pending] => 0 [private] => 0 [trash] => 1 [auto-draft] => 1 [inherit] => 0 [request-pending] => 0 [request-confirmed] => 0 [request-failed] => 0 [request-completed] => 0 ) 1

    So, to find out if you have more than 1 post published try:

    if( wp_count_posts()->publish > 1 ) :
	return true;
else:
	return false;
endif;

  3. Skip to note 9 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

    Basic Example

    The default usage returns a count of the posts that are published. This will be an object, you can var_dump() the contents to debug the output.

    $count_posts = wp_count_posts();