count_users( string $strategy = 'time', int|null $site_id = null ): array

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$strategystringoptional

The computational strategy to use when counting the users.
Accepts either 'time' or 'memory'. Default 'time'.Default: 'time'

$site_idint|nulloptional

The site ID to count users for. Defaults to the current site.Default: null

Return value

array

User counts.

• $total_usersint

  Total number of users on the site.

• $avail_rolesint[]

  Array of user counts keyed by user role.

Performance profile

How much work a call to count_users() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->get_col().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

14–83

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 159.

Plugin surface

1 hook

Third-party callbacks on 'pre_count_users' run inside this call, and their cost is not bounded by anything here.

Called by

1

1 place in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• serializeserialisationmaybe_unserialize()called directly
• sqldatabase query->get_col()called directly
• cacheobject cachewp_cache_switch_to_blog()one call below count_users()

What one call costs · 10 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost count_users() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 1

One hook fires while count_users() runs, in this order:

1. 1
   apply_filters( pre_count_users )filterline 1344 (+20 into the body)

   Filters the user count before queries are run.

Uses · 8

• get_current_blog_id()Retrieves the current site ID.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• is_multisite()Determines whether Multisite is enabled.
• switch_to_blog()Switches the current blog.
• wp_roles()Retrieves the global WP_Roles instance and instantiates it if necessary.
• restore_current_blog()Restores the current blog, after calling switch_to_blog().
• maybe_unserialize()Unserializes data only if it was serialized.
• wp_roles()::get_names()

Used by · 1

• WP_Users_List_Table::get_views()Returns an associative array listing all the views that can be used with this table.

Source code

View on Trac ↗View on GitHub ↗

1324function count_users( $strategy = 'time', $site_id = null ) {1325	global $wpdb;1326 1327	// Initialize.1328	if ( ! $site_id ) {1329		$site_id = get_current_blog_id();1330	}1331 1332	/**1333	 * Filters the user count before queries are run.1334	 *1335	 * Return a non-null value to cause count_users() to return early.1336	 *1337	 * @since 5.1.01338	 *1339	 * @param null|array $result   The value to return instead. Default null to continue with the query.1340	 * @param string     $strategy Optional. The computational strategy to use when counting the users.1341	 *                             Accepts either 'time' or 'memory'. Default 'time'.1342	 * @param int        $site_id  The site ID to count users for.1343	 */1344	$pre = apply_filters( 'pre_count_users', null, $strategy, $site_id );1345 1346	if ( null !== $pre ) {1347		return $pre;1348	}1349 1350	$blog_prefix = $wpdb->get_blog_prefix( $site_id );1351	$result      = array();1352 1353	if ( 'time' === $strategy ) {1354		if ( is_multisite() && get_current_blog_id() !== $site_id ) {1355			switch_to_blog( $site_id );1356			$avail_roles = wp_roles()->get_names();1357			restore_current_blog();1358		} else {1359			$avail_roles = wp_roles()->get_names();1360		}1361 1362		// Build a CPU-intensive query that will return concise information.1363		$select_count = array();1364		foreach ( $avail_roles as $this_role => $name ) {1365			$select_count[] = $wpdb->prepare( 'COUNT(NULLIF(`meta_value` LIKE %s, false))', '%' . $wpdb->esc_like( '"' . $this_role . '"' ) . '%' );1366		}1367		$select_count[] = "COUNT(NULLIF(`meta_value` = 'a:0:{}', false))";1368		$select_count   = implode( ', ', $select_count );1369 1370		// Add the meta_value index to the selection list, then run the query.1371		$row = $wpdb->get_row(1372			"1373			SELECT {$select_count}, COUNT(*)1374			FROM {$wpdb->usermeta}1375			INNER JOIN {$wpdb->users} ON user_id = ID1376			WHERE meta_key = '{$blog_prefix}capabilities'1377		",1378			ARRAY_N1379		);1380 1381		// Run the previous loop again to associate results with role names.1382		$col         = 0;1383		$role_counts = array();1384		foreach ( $avail_roles as $this_role => $name ) {1385			$count = (int) $row[ $col++ ];1386			if ( $count > 0 ) {1387				$role_counts[ $this_role ] = $count;1388			}1389		}1390 1391		$role_counts['none'] = (int) $row[ $col++ ];1392 1393		// Get the meta_value index from the end of the result set.1394		$total_users = (int) $row[ $col ];1395 1396		$result['total_users'] = $total_users;1397		$result['avail_roles'] =& $role_counts;1398	} else {1399		$avail_roles = array(1400			'none' => 0,1401		);1402 1403		$users_of_blog = $wpdb->get_col(

Changelog

Introduced in 3.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.8.8 tag, from src/wp-includes/user.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.