Join Carrie Dils for an in-depth discussion in this video Using apply_filters, part of Advanced WordPress: Action and Filter Hooks.
- [Instructor] Whenever you come across apply_filters in a code base, what it's doing is calling any functions that have been added to that filter hook. It takes three parameters. The first is tag which is going to be the name of the filter hook and then we've got this value and it says mixed $value which is kind of weird so what that is is first the value that we actually want to filter and that's going to be a callback function that returns whatever that value is and then we have these variables that we can additionally pass into the callback function.
And if you recall back to the syntax for add_filter, you may remember that we're passing a default priority of ten and a default number of arguments of one. So let's see how this plays out in this little example here. So let's start with apply_filters and here we've got the tag or the name of the filter hook. Here we've got the value that we want to filter and then we've got these two additional variables that are tagging along. And those variables are going to be passed to my callback function.
So here we've got our example callback function. We've got $string which is going to be the value to filter and then these two optional arguments. We're returning simply the string or the value and then we're using this add_filter to call this function here. Now I don't know about you but that all sounds kind of confusing to me and I don't think the WordPress codex always does the best job of explaining things so let me show you how this might work in a different situation. So let's say that I've got this function called invitation_list and in that function is a variable called guests and it's set to an array with Carrie, Major, and Bert and all that function does is return that value for guests.
So if I were to echo the function invitation_list it would just output CarrieMajorBert. But what if I wanted to provide a way for myself or maybe another developer to come back later on and edit that list of guests there? Well that's where apply_filters would come in handy. So after I've set my initial array and assigned that to that guests variable. Now I'm saying I want to apply a filter to that list and I'm going to do it with a filter hook called vip_list and I'm also going to pass guests which is the value that we want to filter.
So let's go with a function called add_people and I'm passing in that variable of guests. Now I'm defining a new variable, extra_guests, and in this one, because guest was an array that I was working with earlier, I want to be sure that I'm going to be working with an array here. So I say extra_guests and edited array and I'm adding a name Flynn. So now after that I've got my variable guests and I'm merging the array of the original guest list with my extra guests and then returning guests.
So the final step in the process to use that filter I want to say add_filter and then I want to hook to that vip_list and then I want to run my callback function add_people. So now in theory, when I echo my invitation list it would output CarrieMajorBertFlynn. The bottom line is that whenever we use add_filter we're able to take advantage of where apply_filters has been used in a code base. Apply_filters is pretty magical because instead of having to go completely rewrite a function, in this case invitation_list, to include Flynn, I can just simply use a filter that's already there to add additional guests to my list.
Apply_filters are awesome.
- Actions and filters explained
- Identifying available hooks and filters
- Looking at load order
- Understanding callback functions
- Creating custom hooks
- Using third-party hooks
- Building a new WordPress plugin with filters and actions