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.
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.
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.
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.
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' ) ) :
And will end with:
Your plugged function will, at the very least, carry the same name as the plug-in’s function thus overriding it.
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.