Customizing WP-Members™ with pluggable functions

There are many requests that come into this blog asking how to customize certain elements of the WP-Members™ plug-in. While I’ve made attempts to have WP-Members™ be as flexible as possible, there are times when a specific customization request would be outside the exiting process flow of the plug-in and would require making changes directly to the functions in the plug-in itself.  

Making direct changes to the functions within the plug-in is discouraged because it puts the user in a difficult situation. These types of changes are generally referred to as “hacks” and hacks must be reapplied anytime you upgrade the plug-in. Avoiding upgrades because of the need to update your hacks is a bad practice because upgrades often include important security updates.

So to make things a little more extensible, I have introduced pluggable functions to the WP-Members™ plug-in. Pluggable functions are functions that can be recreated outside of the plug-in itself without the need to make changes to the core script files directly. This actually was introduced out of my own needs as I have clients using the plug-in in a customized way and everytime I do an upgrade, I need to make sure their customizations stay compatible. This method has been working well in that regard, and so it is being introduced to the public users of the plug-in as well.

Caveats, Caution, Etc.

The process is not without its own caveats. For starters, you will need some basic understanding of PHP. Don’t let that scare you too much, because in general, you should be able to back out of your changes fairly easily. But I must warn you that you should know what you are doing if you deal with any code that makes any changes to your data (i.e. writing to the database).

You will also need to be aware that changes in an update may affect your plugged functions. You may still need to make updates and changes once your customizations are put into place. It is just that you won’t be doing this within the plugin itself. But you will still need to keep careful track of any updates that have been put into place with a new version release.

WordPress Standards

The WP-Members™ project attempts to follow WordPress best practices when it comes to development. This includes how the functions are named, commented, and documented.

Function Names

All (or almost all) of the functions within WP-Members™ carry a prefix of wpmem_ followed by the name of the function (admin functions are wpmem_a_name-of-function). This is to avoid the possibility of name collisions with WordPress functions or functions from another plugin.

Comments

I have tried to keep up with comments in the code, but it doesn’t always work out that way. But, in general, if something is new or has been changed from a previous version, then it is noted in the comments. This will be important to you in keeping your plugged functions up-to-date by knowing what changes have been made.

Documentation

WP-Members™ attempts to follow the PHP DocBlock standards. This is the location before the function that gives you information about the function, what it does, and what it needs.

Putting it all together

A pluggable function in WP-Members™ will be wrapped with the line:

if( ! function_exists( 'wpmem_name-of-function' ) ) :

It will end with this:

endif;

Your plugged function will, at the very least, carry the same name as the plug-in’s function thus overriding it.

Getting Started

To begin using pluggble functions in WP-Members, you will need to create a php file to store your functions in. Create a file named wp-members-pluggable.php and save it to your WordPress plugins directory. This file acts as a drop-in for the plug-in. When WP-Members™ is loaded by WordPress, it checks for the existence of wp-members-pluggable.php and if it is available, it will load it first.

IMPORTANT: the file MUST be named wp-members-pluggable.php and MUST be saved to your WordPress plugins directory, NOT the /plugins/wp-members/ directory. That way, it will not be overwritten when you upgrade the WP-Members™ plugin.

The easiest way to handle this is to copy the existing function to your wp-members-pluggable.php file.  Then make the changes to the function you need.  Based on most of the user requests I receive, this generally will amount to adding another function into the process.  For example, within the existing function, you want another process to occur.

I suggest that additional processes that you add be added as function calls (with the additional function process also stored in the pluggable file) to keep the original function as clean as possible.  This will make it easier to compare to any new version that come out so you know if you need to update the plugged function.

Comments

  1. Robert says

    Hi Chad,
    I’d like to allow people to login using either their username or email so I tried installing wp-email-login but it doesn’t seem to work out of the box with a site using WP-Members. Is this a good candidate for a pluggable function like you mention here? Do you have a page or post with a list of pluggable functions that I could review to see if any would be useful?
    Thanks,
    Robert

  2. Morteza Rezvani says

    Hi.
    Thank you for wp-members, it’s great.
    I have a question, how i can add display name in member area and how i can change default users display name to first name and last name when they registered ?
    I’m sorry for my bad english.

  3. Marx Consuegra says

    Hi I’m new on wp-members plug-in, I’m having some trouble on how to add a dropdown menu for Date, Month and Year.

    Thanks for any help guys :)

  4. David Ransier says

    I’m working on a site that uses WP-Memebrs plugin and I’m trying to do some simple modifications via the Pluggable methodology.

    I think I must be doing something wrong, can you help please.

    I created the file: wp-content/plugins/wp-members-pluggable.php, and it contains the following code:

    <?php
    if( ! function_exists( 'wpmem_inc_status' ) ):
    /**
    * Generate users login status if logged in and gives logout link
    *
    * @since 1.8
    * @global $user_login
    * @return string $status
    */
    function wpmem_inc_status()
    {
    global $user_login;
    $logout = get_bloginfo( 'url' ) . '/?a=logout';

    $status = '’ . sprintf( __( ‘You are registered as %s’, ‘wp-members’ ), $user_login )
    . ‘ | ‘ . __( ‘click here to logout’, ‘wp-members’ ) . ‘‘;

    return $status;
    }
    endif;
    ?>

    The only change I made was “logged in” to “registered”. This isn’t actually the change I want to make, but I’m proving the process first.

    Regardless of what I try, it always shows “logged in”.

    Thanks,

Trackbacks

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>