Today’s article continues our discussion of WordPress’s Hooks system with a practical look at the direct opposite of add_action()
and add_filter()
: remove_action()
and remove_filter()
.
About remove_action()
and remove_filter()
Before we tell you how to use these functions, let’s talk about why and when.
What They’re Good For
remove_action()
andremove_filter()
have one purpose: to cancel out existing calls toadd_action()
andadd_filter()
.
remove_action()
and remove_filter()
have one purpose: to cancel out existing calls to add_action()
and add_filter()
somewhere in your site’s code.
In other words, someone who wrote code you’re running thought that a particular action function or filter function needed to run, and you’re saying, “No, it doesn’t.”
Why to Use Them Instead of Just Deleting Things
remove_action()
andremove_filter()
let you dictate the functionality you want on your site, while still being able to update third-party themes and plugins.
So why would you use remove_action()
and remove_filter()
, instead of just deleting the original add_action()
or add_filter()
call?
Well, if it’s all your own code, you probably should simply remove the hooked functions you no longer intend to use. But in WordPress, you’re often working with other people’s code—both themes and plugins—, and it’s best not to touch that code or you’ll lose your modifications when you update. So remove_action()
and remove_filter()
are useful to impose only the functionality you want on your site, while keeping the themes and plugins that are running updatable.
remove_action()
andremove_filter()
aren’t terribly common in my day-to-day work.
With that said, I find that remove_action()
and remove_filter()
aren’t terribly common in my day-to-day work. They’re more common in super-event-driven systems like the Genesis Framework or WooCommerce—and, in fact, the real-life examples below both come from WooCommerce. Let’s take a look!
A Practical Example of remove_action()
The most immediate use case I’ve found for remove_action()
is to remove product images in WooCommerce. WooCommerce is a highly event-driven system, and removing product images is not a process of editing templates, but of unhooking functions.
Let’s take a look at the code, and the results:
remove_action( 'woocommerce_before_shop_loop_item_title', 'woocommerce_template_loop_product_thumbnail' );
The code above changes the display of the main Shop page from this:
Into this:
remove_action()
Arguments
As you can see, remove_action()
has two required arguments:
- The name of the action hook you’re interested in
- The name of the function you want to unhook
There’s also an optional third value, which is an integer for the “priority” of the function you’re looking for. If you don’t specify this third value, it defaults to a priority of 10, which is also the default priority if you call add_action()
without specifying priority. (If this discussion’s confusing you, check out the bit about priority in the Codex’s entry on add_action()
.)
In sum, if the original add_action()
includes a third argument, you’ll need to as well. Otherwise, if, say, the add_action()
call hooks in the function with priority 999, that means that it’s set to hook in after your remove_action()
goes looking for it—meaning that remove_action()
won’t do anything.
The bit that’s slightly odd about remove_action()
‘s third argument is that if you specify this third value, you need to specify the exact priority of the original call. So you can’t simply set priority to 10 and remove the add_action()
call if it’s “10 or earlier,” or “999 or earlier”: 10 will only remove add_action()
calls with priority 10, and 999 will only remove calls with priority 999.
A Practical Example of remove_filter()
Let’s stay with WooCommerce. WooCommerce often doesn’t want people to know they’re in WordPress, so it uses a filter function called wc_lostpassword_url()
to redirect “Lost Your Password?” requests from wp-login.php
over to /my-account/lost-password
, on the front-end of the site.
Let’s take a look at wc_lostpassword_url()
from WooCommerce’s code:
/* Location: woocommerce/includes/wc-account-functions.php */
function wc_lostpassword_url( $default_url = '' ) {
$wc_password_reset_url = wc_get_page_permalink( 'myaccount' );
if ( false !== $wc_password_reset_url ) {
return wc_get_endpoint_url( 'lost-password', '', $wc_password_reset_url );
} else {
return $default_url;
}
}
add_filter( 'lostpassword_url', 'wc_lostpassword_url', 10, 1 );
This function hooks onto the WordPress filter hook lostpassword_url
. It filters out the original admin password retrieval URL, and replaces it with a URL of its own choosing. The end result looks like this:
Removing the Filter
Let’s say we don’t want that filter running. Instead, we want our users to hit the original WordPress password retrieval page. We simply write the following into our functions.php
:
remove_filter( 'lostpassword_url', 'wc_lostpassword_url' );
Now, when you indicate that you’ve lost your password on the site, you’re directed here:
Of course, after removing WooCommerce’s filter, you could add your own filter that takes the user anywhere, even to http://google.com
. But removing WooCommerce’s redirect filter is the first step.
remove_filter()
‘s Arguments
remove_filter()
is almost identical to remove_action()
. Its two required arguments are:
- The name of the filter hook you’re interested in
- The name of the function you want to unhook
You can also specify a third argument, the priority with which the function was hooked on. We got to skip that in this case, because wc_lostpassword_url()
is hooked on with the default priority of 10.
Happy Unhooking!
This short article has explained the uses of remove_action
and remove_filter
, and given a couple of practical demos. For a more detailed look you can see our course: A Complete Introduction to the WordPress Hooks System. Hopefully you feel confident to unhook things as needed on your own site. Thanks for reading!
[…] Off the Hook: Practical Uses of remove_action() and remove_filter() […]
[…] Practical Uses of remove_action() and remove_filter() […]