Display online Users on WordPress

Earlier today I ran into a problem where I needed a simple way to display which registered users are online right now on the site.

I've done a Video explaining what was my solution and how to apply it to a theme, but I myself hate when I see a video without any code that I can easily take a look at, so below the video you will find a explanation of the code step by step, and in the end the plugin I created for this purpose.

Please note that I will comment further the code on the video, but there are some comments on each one of the snippets here


Variables used

We will use only two variables on this plugin:

  • static protected $_instance = null; -- Holds the static instance of our class after the plugin is initialized
  • static protected $prefix = 'OnlineNow'; -- Prefix we will use on the Database Options

Class Instance handling

When dealing with plugins in WordPress a good practice is to save a static variable of the main class on a private/protected variable and create a static method to instantiate the class whenever you call this method the first time:

static public function instance(){
    null === self::$_instance and self::$_instance = new self;
    return self::$_instance;
}

Plugin Initialization

Here is where our plugin will hook into WordPress and do the required actions to allot this plugin to work as we expect.

static public function init(){
    // Lock this class to be initialized only once
    if ( null !== self::$_instance ){
        return false;
    }
    add_action( 'wp_login', array( self::instance(), 'login' ), 10, 2 );
    add_action( 'clear_auth_cookie', array( self::instance(), 'logout' ), 10 );

    // Register Shortcodes
    add_shortcode( 'online:list', array( self::instance(), 'shortcode_list' ) );
    add_shortcode( 'online:qty', array( self::instance(), 'shortcode_qty' ) );

    add_filter('widget_text', 'do_shortcode');

    return true;
}

Register when a User logs in

We need to register when a user do the login so that we can save it in the database to grab this value and display for the users.

public function login( $user_login, $user ) {
    $users = get_option( self::$prefix . '-users', array() );

    if ( in_array( $user->ID, $users ) ){
        return;
    }

    $users[] = $user->ID;

    update_option( self::$prefix . '-users', $users );
}

Register when a User logs out

Just like when we register the action of login and add the user ID to the database option, now we will remove that ID when the user logs out.

public function logout() {
    $users = get_option( self::$prefix . '-users', array() );

    $user_id = get_current_user_id();

    if ( ! in_array( $user_id, $users ) ){
        return;
    }

    update_option( self::$prefix . '-users', array_diff( $users , array( $user_id ) ) );
}

Grab the users logged in

We need a method that will allow us to get the users from the database option, I've also allowed the developer to exclude or include a user to the list.

public function get_users( $include = array(), $exclude = array() ){
    // Retrieve the users from Database
    $users = get_option( self::$prefix . '-users', array() );

    // Parse Shortcode atts to exclude
    if ( is_string( $exclude ) ){
        $exclude = array_map( 'trim', explode( ',', $exclude ) );
    }

    // Exclude users based on shortcode attribute
    $users = array_diff( (array) $users, (array) $exclude );

    // Parse Shortcode atts to include
    if ( is_string( $include ) ){
        $include = array_map( 'trim', explode( ',', $include ) );
    }

    // Include users based on shortcode attribute
    $users = array_merge( (array) $users, (array) $include );

    // Garantee that the array is safe for usage
    $users = array_unique( array_filter( (array) $users ) );

    // Remove all non existent users
    $users = array_map( array( $this, 'user_exists' ), $users );

    // Garantee that the array is safe for usage
    $users = array_filter( (array) $users );

    return $users;
}

Then I used a method inside of the get_users to check if the user exists before return the list of WP_User objects - on video.

public function user_exists( $user_id ){
    $user = new WP_User( $user_id );

    // Check if the users exists
    if ( ! $user->exists() ){
        return false;
    }

    return $user;
}

List Online Users Shortcode

After we did all the hard work of storing the data about user on the database, now we will use that information to print an HTML with the list of users that are currently online.

public function shortcode_list( $atts ) {
    $atts = (object) shortcode_atts( array(
        'avatar' => false,

        'exclude' => '',
        'include' => '',
    ), $atts );

    $users = $this->get_users( $atts->include, $atts->exclude );

    $html = '<ul class="users-online">';
    foreach ( (array) $users as $user ) {
        $html .= '<li>';
        // Allow the user to control the avatar size and if he wants to show
        if ( is_numeric( $atts->avatar ) ){
            $html .= get_avatar( $user , $atts->avatar );
        }
        $html .= '<span>' . $user->display_name . '</span>';
        $html .= '</li>';
    }
    $html .= '</ul>';
    return $html;
}

Display the quantity of Users Online

The user might also want to display the quantity of users that are online with a shortcode, so we will deal with that too.

public function shortcode_qty( $atts ) {
    $atts = (object) shortcode_atts( array(
        'plural' => __( '%s users online', 'online-now' ),
        'singular' => __( 'One user online', 'online-now' ),
        'zero' => __( 'Zero users online', 'online-now' ),

        'numeric' => false,

        'exclude' => '',
        'include' => '',
    ), $atts );

    $users = $this->get_users( $atts->include, $atts->exclude );

    if ( $atts->numeric ){
        return count( $users );
    }

    if ( count( $users ) === 0 ) {
        $text = $atts->zero;
    } elseif ( count( $users ) === 1 ) {
        $text = $atts->singular;
    } else {
        $text = $atts->plural;
    }

    return sprintf( $text, count( $users ) );
}

Repository and Download

You can always checkout the oficial repository for this plugin and/or download the latest version of the code to install it in your WordPress.

How to make WordPress Database Case Insensitive

When I started to work with WordPress I didn't know anything about how databases works or anything related to encoding and character set, but as I started into adventure myself on places like pre_get_posts, and the WP_Query filters such as posts_join and posts_where, I quickly found that understanding how the database works was a key to unlocking better performance.

Once I was trying to do a search on some User meta data and I didn't know why one of my results where not been shown as I expected so delving further and debugging I found that there an information called Collation which is the set of Rules that your database table will follow.

The problem was this meta data was a city value, and I did not have control over the user input so it needed to be case-insensitive, which was not happening because the Collation was set to be utf8_bin that will make your MySQL compare queries that involve LIKE via a Binary structure so it will A is not equal to a.

This case sensibility issue on WordPress databases or any MySQL is easy to solve, you just need to change the collation of the tables that you want to be insensitive by executing the following SQL query on your database.

ALTER TABLE `wp_posts` CONVERT TO CHARACTER SET utf8 COLLATE utf8_unicode_ci;
ALTER TABLE `wp_postmeta` CONVERT TO CHARACTER SET utf8 COLLATE utf8_unicode_ci;

Where the _ci at the end will convert the Collation to be Case Insensitive, remember that changing the Collation of a table might lead you to have security problems of people trying to pose as Administrator account, which in WordPress is not the case because there are validations for that but if you are in another system you might want to double check.

WordCamp São Paulo 2014

No próximo sábado vou estar em São Paulo falando sobre como contribuir para o WordPress sendo você um desenvolvedor, designer, tradutor ou usuário!

Sendo a grande força da ferramenta a sua comunidade extremamente colaborativa e receptiva a novos membros, vamos nesses 40 minutos entender como funciona a participação e contribuição individual para que essa grande qualidade do WordPress seja feita de forma sólida e bem estruturada pela comunidade Brasileira.

Confira o resto da programação do WordCamp São Paulo 2014 e faça parte desse evento.

Espero você por lá!