IMPORTANT: This article remains here for legacy purposes. There are many users who utilize pluggable functions in the plugin and have not updated these processes to utilize hooks and filters. There are also articles buried in this blog that have customizations that use a pluggable function (if you find one, let me know). HOWEVER, pluggable functions, while still supported, are not the preferred way of customizing plugin features. Like WordPress core, these were the original way to customize, but as filter and action hooks were added to the application, pluggable functions were not longer necessary. The API for WP-Members is much more mature than it was when pluggable functions were introduced. There really should be no reason to use pluggable functions at this point. If you are working on customizing on your own and you see no other way than to use a pluggable function, mention it to me as there may be a better way, or maybe there needs to be a new filter or action in the plugin.
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 way the plugin can be customized so that when you upgrade, your customizations will not be overwritten.
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 generally wpmem_a_name_of_function or wpmem_admin_name_of_function). This is to avoid the possibility of name collisions with WordPress functions or functions from another plugin.
Documentation
WP-Members follows PHP DocBlock and WordPress coding standards. The location before the function that gives you information about the function, what it does, what parameters it accepts and what it returns. There are additional comments through the functions as well.
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:
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.