I was asked a few days ago to create a system would ban a WordPress user from an install. So I created a simple plugin and I wanted to share with you the basics of this plugin. In this tutorial we will be covering WordPress filters, actions, users columns management and some more great things.
Step 1: Create The Plugin
Once again, here it’s very complicated, all you have to do is to create a new folder with “wp-content/plugins” called “ban-users”. In this folder, create a new file called “ban-users.php”, open it an paste this code:
<?php
/*
Plugin Name: Ban Users
Plugin URI: http://www.remicorson.com
Description: Allows you to ban users
Author: Remi Corson
Version: 1.0
Author URI: http://www.remicorson.com
*/Step 2: Add A Checkbox On Users’ Profile Page
The first thing we need to to do is to add a checkbox on each user profile edition page. When you’ll check this checkbox it will store a user meta option that will indicated that the user isn’t allowed anymore to login to your website.
Here is the code:
/**
* Admin init
*
* @access public
* @since 1.0
* @return void
*/
function rc_admin_init(){
// Edit user profile
add_action( 'edit_user_profile', 'rc_edit_user_profile' );
add_action( 'edit_user_profile_update', 'rc_edit_user_profile_update' );
}
add_action('admin_init', 'rc_admin_init' );This code is simply creating a call to a function that we have to create now. This function will add a checkbox to users profile page.
/**
* Adds custom checkbox to user edition page
*
* @access public
* @since 1.0
* @return void
*/
function rc_edit_user_profile() {
if ( !current_user_can( 'edit_users' ) ) {
return;
}
global $user_id;
// User cannot disable itself
$current_user = wp_get_current_user();
$current_user_id = $current_user->ID;
if ( $current_user_id == $user_id ) {
return;
}
// Check if enabled
$checked = checked( get_user_option( 'rc_banned', $user_id, false ) );
// Display checkbox
echo '<table class="form-table">
<tr>
<th scope="row">Ban User</th>
<td>
<label for="rc_ban">
<input name="rc_ban" type="checkbox" id="rc_ban" '. $checked .' />Ban this user</label>
</td>
</tr>
</table>';
}We now need to have the function that will save into the database the value of the checkbox:
/**
* Save custom checkbox
*
* @access public
* @since 1.0
* @return void
*/
function rc_edit_user_profile_update() {
if ( !current_user_can( 'edit_users' ) ) {
return;
}
global $user_id;
// User cannot disable itself
$current_user = wp_get_current_user();
$current_user_id = $current_user->ID;
if ( $current_user_id == $user_id ) {
return;
}
// Lock
if( isset( $_POST['rc_ban'] ) && $_POST['rc_ban'] = 'on' ) {
rc_ban_user( $user_id );
} else { // Unlock
rc_unban_user( $user_id );
}
}As you can see this new function uses two other functions: rc_ban_users() and rc_unban_users(). Their names are pretty explicit, the first one will store in the database the fact that a user is ban, the second will unlock users.
Step 3: Ban Users
It’s now time to create the rc_ban_users() function. In this function we need to check if a value is already stored, and if not we need to store the value. That’s the reason why i call a function that I’ll describe later: rc_is_user_banned():
/**
* Ban user
*
* @access public
* @since 1.0
* @return void
*/
function rc_ban_user( $user_id ) {
$old_status = rc_is_user_banned( $user_id );
// Update status
if ( !$old_status ) {
update_user_option( $user_id, 'rc_banned', true, false );
}
}Step 4: Un-ban Users
The following function is the opposite as the one we just created: we have to give the ability to “un-ban” users:
/**
* Un-ban user
*
* @access public
* @since 1.0
* @return void
*/
function rc_unban_user( $user_id ) {
$old_status = rc_is_user_banned( $user_id );
// Update status
if ( $old_status ) {
update_user_option( $user_id, 'rc_banned', false, false );
}
}Step 5: Is User Banned?
We saw in rc_ban_users() and rc_unban_users() that we use a function called rc_is_user_banned() to check if a user is banned or not. Let’s create it:
/**
* Checks if a user is already banned
*
* @access public
* @since 1.0
* @return void
*/
function rc_is_user_banned( $user_id ) {
return get_user_option( 'rc_banned', $user_id, false );
}Basically, this function simply returns the value of the option saved in rc_ban_users().
At this time we have a new checkbox on the user edition page that should like that:
The last step is to hook a function to the login form to avoid banned users to login.
Step 5: Avoid Banned Users To Login
To do so we need to use a WordPress default filter called “wp_authenticate_user”. To this filter we’ll hook a function called “rc_authenticate_user()”. This function will use the WP_Error class.
/**
* Check if user is locked while login process
*
* @access public
* @since 1.0
* @return void
*/
function rc_authenticate_user( $user ) {
if ( is_wp_error( $user ) ) {
return $user;
}
// Return error if user account is banned
$banned = get_user_option( 'rc_banned', $user->ID, false );
if ( $banned ) {
return new WP_Error( 'rc_banned', __('<strong>ERROR</strong>: This user account is disabled.', 'rc') );
}
return $user;
}Now, we just need to add the filter:
add_filter( 'wp_authenticate_user', 'rc_authenticate_user', 1 );We created a plugin that adds a checkbox to the user profile edition page. We used a second function to store the value on the checkbox and we create a function to ban a WordPress user and another on to unlock a user. We also created a small function to check if a user is banned or not. And we finally hooked a function to the “wp_authenticate_user” filter using the WP_Error WordPress default class.