The WP-Members plugin offers a great deal of extensibility and customization through the use of filter and action hooks, much like WordPress. These operate the same way you would use any other WordPress hook.
Where do I put my action/filter function?
Your custom functions (and the add_action/add_filter call) can go either in your theme functions.php file or in a custom plugin file.
NOTE: If you are using a functions.php file, it should be noted that best practices are to be using a child theme for your customizations so that any updates to the theme itself are not overwritten when you upgrade.
How do I use an action/filter hook?
The WP-Members hooks are used just like other WP hooks, using add_filter or add_action to call them.
Action hooks are called as follows:
add_action( $tag, $function_to_add, $priority, $parameters );Filter hooks are called as follows:
add_filter( $tag, $function_to_add, $priority, $parameters );What the parameters are
$tag: this is the name of action/filter you are hooking the $function_to_add to.
$function_to_add: the name of the function to be run when the action is done or the filter is applied.
$priority: (optional) this is the “priority” to run the function when the hook is triggered. This is optional and is often omitted. If omitted, it runs at a priority of “10”. When the hook is triggered, functions run in the order of the priority value. You generally only need to specify priority if you need your specific filter or action function to fire before or after another function hooked to the same filter or action.
$parameters: (optional) this specifies the number of parameters to pass to your hooked function. The default is 1, and unless you have specific additional arguments, you can omit this value. If however, the function requires additional arguments (parameters), you must specify this value (and in order to specify this value, you’ll need to include the $priority value as well). The number of available arguments and what they are is always noted in the hook’s documentation. For filters, the item being filtered is always the first/default argument.
Examples
Here is an example of how to use a filter hook. This example uses the wpmem_login_redirect filter. All of this would be added to your functions.php file.
Add the filter
First, call the filter with the add_filter function and set the function you want to run at that point:
add_filter( 'wpmem_login_redirect', 'my_redirect' );What is this doing?
This is telling WordPress that when the login function is run and it reaches the “wpmem_login_redirect” hook point, run the function “my_redirect” to filter that result.
Add the function
And here is the function for the example:
function my_redirect( $original_value_being_filtered ) {
$value_to_return = 'http://mysite.com/my-redirected-page';
return $value_to_return;
}Note the name of the function matches name of the function we asked to call in the “add_filter” section.
The function “my_redirect()” will accept as an argument the original value that we would be redirecting to. This is defined in the hook’s documentation. You can use this for whatever purpose, or as in this case, ignore it completely. In this example, I’m just sending back a new URL and ignoring the original.
To give those of you who do not have experience with WordPress filters a little more insight into the power of these hooks, you can use various WordPress functions and other PHP to make any kind of determinations you wish before returning the value. That means you could redirect users based on certain criteria (such as their first login), or based on what page they are logging in from, etc. That is up to you. When your function has determined what the result is, then it returns that value.
For more information on WordPress Hooks, see this page in the Codex: http://codex.wordpress.org/Plugin_API/Hooks