create_users WordPress user capability

create_users WordPress capability

create_users WordPress capability

WordPress user capability create_users is straight forward and self-explained one. WordPress Codex Roles and Capabilities page even doesn’t contain a word explaining or defining it.

You can know from that page only that this capability was added to WordPress since version 2.1 and it is included into Administrator role by default. It belongs to Superadmin (for multi-site configuration) also, but you can not see such role in WordPress roles list.

Do you wish to know a little more about this capability or dive deeper into WordPress user capabilities world? Follow me reading this post and you will get detailed report about how and there create_users capability is used by WordPress.

Searching WordPress core source code for ‘create_users’ keyword returns me list from 13 files:

All stuff above concerns blocking user from access to the new user creating functionality and/or show/hide ‘Create/Add New User’ links in the WordPress user interface. In some places if you have not ‘create_users’ capability “Add new user” is replaced by “Add Existing User” or “Invite User” links, in case you have ‘promote_users’ capability instead.
Look directly on the quotes from WordPress source code below to get right information about create_users capability.

wp-admin/admin-ajax.php
allows to add new users via AJAX call, needed user attributes as login, password, email, etc. shoulg be send with POST request:

892
893
894
895
896
897
case 'add-user' :
	check_ajax_referer( $action );
	if ( !current_user_can('create_users') )
		die('-1');
        if ( !$user_id = add_user() )
		die('0');

wp-admin/menu.php
In this file WordPress defines condition if user can add new user himself, or he just promote new user.

172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
if ( current_user_can('list_users') ) {
	$_wp_real_parent_file['profile.php'] = 'users.php'; // Back-compat for plugins adding submenus to profile.php.
	$submenu['users.php'][5] = array(__('All Users'), 'list_users', 'users.php');
	if ( current_user_can('create_users') )
		$submenu['users.php'][10] = array(_x('Add New', 'user'), 'create_users', 'user-new.php');
	else
		$submenu['users.php'][10] = array(_x('Add New', 'user'), 'promote_users', 'user-new.php');
 
	$submenu['users.php'][15] = array(__('Your Profile'), 'read', 'profile.php');
} else {
	$_wp_real_parent_file['users.php'] = 'profile.php';
	$submenu['profile.php'][5] = array(__('Your Profile'), 'read', 'profile.php');
	if ( current_user_can('create_users') )
		$submenu['profile.php'][10] = array(__('Add New User'), 'create_users', 'user-new.php');
	else
		$submenu['profile.php'][10] = array(__('Add New User'), 'promote_users', 'user-new.php');
}

wp-admin/user-new.php
In case of multi-site environment user needs to have one of two capabilities to proceed with this code: create_users or promote_users. For single-site WordPress configuration you should have create_users to proceed.

12
13
14
15
16
17
if ( is_multisite() ) {
	if ( ! current_user_can( 'create_users' ) && ! current_user_can( 'promote_users' ) )
		wp_die( __( 'Cheatin’ uh?' ) );
} elseif ( ! current_user_can( 'create_users' ) ) {
	wp_die( __( 'Cheatin’ uh?' ) );
}

Btw, if you curiouse, promote_users capability allows user under multi-site environment to add existing user to the current blog or invite user by email to subscribe for this blog.

create_users capability is checked again before execute ‘createuser’ action in oppose to ‘adduser’ action, which is not used for creation of new users, just for adding existing user to the blog or send him an invitation

89
90
91
92
93
} elseif ( isset($_REQUEST['action']) && 'createuser' == $_REQUEST['action'] ) {
	check_admin_referer( 'create-user', '_wpnonce_create-user' );
 
	if ( ! current_user_can('create_users') )
		wp_die(__('Cheatin’ uh?'));

Next create_users capability is checked and used to manage parts of user interface user sees on the user-new.php page:

138
139
140
$do_both = false;
if ( is_multisite() && current_user_can('promote_users') && current_user_can('create_users') )
	$do_both = true;
216
217
218
219
220
if ( current_user_can( 'create_users' ) ) {
	echo _x( 'Add New User', 'user' );
} elseif ( current_user_can( 'promote_users' ) ) {
	echo _x( 'Add Existing User', 'user' );
} ?>
289
290
291
if ( current_user_can( 'create_users') ) {
	if ( $do_both )
		echo '<h3 id="create-new-user">' . __( 'Add New User' ) . '</h3>';

wp-admin/user-edit.php
In case page user-edit.php is called not for user profile, you can see “Add New” user link, if you have ‘create_users’ capability.

184
185
186
187
188
189
190
if ( ! IS_PROFILE_PAGE ) {
	if ( current_user_can( 'create_users' ) ) { ?>
		<a href="user-new.php" class="add-new-h2"><?php echo esc_html_x( 'Add New', 'user' ); ?></a>
	<?php } elseif ( is_multisite() && current_user_can( 'promote_users' ) ) { ?>
		<a href="user-new.php" class="add-new-h2"><?php echo esc_html_x( 'Add Existing', 'user' ); ?></a>
	<?php }
} ?>

wp-admin/users.php
Again, WordPress checks user-edit.php to know if it should show “Add New” or “Add Existing” user link.

396
397
398
399
400
if ( current_user_can( 'create_users' ) ) { ?>
	<a href="user-new.php" class="add-new-h2"><?php echo esc_html_x( 'Add New', 'user' ); ?></a>
<?php } elseif ( is_multisite() && current_user_can( 'promote_users' ) ) { ?>
	<a href="user-new.php" class="add-new-h2"><?php echo esc_html_x( 'Add Existing', 'user' ); ?></a>
<?php }

wp-admin/includes/dashboard.php
If you can create_users capability, you will see “Create a New User” link at “Right Now” admin back-end dashboard widget.

440
441
	if ( current_user_can('create_users') )
		$actions['create-user'] = '<a href="' . network_admin_url('user-new.php') . '">' . __( 'Create a New User' ) . '</a>';

wp-admin/includes/schema.php
User capability create_users was added to WordPress permissions system since version 2.1.0

684
685
686
687
688
	$role =& get_role('administrator');
	if ( ! empty($role) ) {
		$role->add_cap('delete_users');
		$role->add_cap('create_users');
	}

wp-admin/network/menu.php
Network management menu shows “Add New” item if super-admin has create_users capability only.

20
21
22
 $menu[10] = array(__('Users'), 'manage_network_users', 'users.php', '', 'menu-top menu-icon-users', 'menu-users', 'div');
 $submenu['users.php'][5]  = array( __('All Users'), 'manage_network_users', 'users.php' );
 $submenu['users.php'][10]  = array( _x('Add New', 'user'), 'create_users', 'user-new.php' );

wp-admin/network/site-users.php

248
249
250
251
252
	<?php if ( current_user_can( 'create_users' ) && apply_filters( 'show_network_site_users_add_new_form', true ) ) : ?>
<p><?php _e( 'You may add from existing network users, or set up a new user to add to this site.' ); ?></p>
	<?php else : ?>
<p><?php _e( 'You may add from existing network users to this site.' ); ?></p>
	<?php endif; ?>
281
282
283
 <?php if ( current_user_can( 'create_users' ) && apply_filters( 'show_network_site_users_add_new_form', true ) ) : ?>
 <h5 id="add-new-user"><?php _e('Add New User') ?></h5>
 <form action="<?php echo network_admin_url('site-users.php?action=newuser'); ?>" id="newuser" method="post">

wp-admin/network/user-new.php

16
17
 if ( ! current_user_can('create_users') )
	wp_die(__('You do not have sufficient permissions to add users to this network.'));

wp-admin/network/users.php

281
282
283
	if ( current_user_can( 'create_users') ) : ?>
		<a href="<?php echo network_admin_url('user-new.php'); ?>" class="add-new-h2"><?php echo esc_html_x( 'Add New', 'user' ); ?></a><?php
	endif;

wp-includes/admin-bar.php

504
505
	if ( current_user_can( 'create_users' ) || current_user_can( 'promote_users' ) )
		$actions[ 'user-new.php' ] = array( _x( 'User', 'add new from admin bar' ), 'new-user' );

wp-includes/capabilities.php
function map_meta_cap() processes ‘create_users’ capability this way:

1155
1156
1157
1158
1159
1160
1161
1162
	case 'create_users':
		if ( !is_multisite() )
			$caps[] = $cap;
		elseif ( is_super_admin() || get_site_option( 'add_new_users' ) )
			$caps[] = $cap;
		else
			$caps[] = 'do_not_allow';
		break;

Tags: ,