Join Carrie Dils for an in-depth discussion in this video Understanding callback functions, part of Advanced WordPress: Action and Filter Hooks.
- [Instructor] In programming terms, a callback function is simply a function that gets passed as an argument to another function. You've already seen some basic examples of them in this course but I wanted to specifically call them out. See what I did there? Here we're looking at the syntax for the add_action function. The first parameter here is the name of our hook which is telling WordPress when to run. The second parameter here is our callback function. It tells WordPress what to run when it reaches the hook.
I've been referring to it as simply a function but to get more specific about it, it's called a callback function. Let's look at an example. This is the pre_get_posts action hook and it's used to modify the WordPress query. The query object would be passed to your function by reference. If we scroll down the page here let's look at an example of how this callback function could work. So we've got a callback function called exclude_category. We're passing in that query object and then we've got a couple of WordPress conditional statements here so we're saying if the query is on the main homepage and if we're dealing with the main query then we're going to set the query.
This instance we are excluding some categories from that query. And then of course for that callback function to actually run we need to attach it to this pre_get_posts hook. So that's an example callback function for pre_get_posts. One more thing I want to point out here, and this goes back to load order. Here we've got some instructions of when it's too late to use the pre_get_posts hook and it's basically when the query has already been set. So for instance if you were to use pre_get_posts in a theme template file such as single or archive it's entirely too late.
The query ship has sailed. So there was a look at an action hook using a callback function. Let's see how it works with add_filter. So same thing, we've got the hook that we're hooking into and then we've got this callback function and just like action, it defaults to a priority of ten and a single argument that we're going to pass back to our callback function. We'll take a look at an example of this login redirect filter. Now this one actually takes up to three parameters.
The first is where you want to redirect the user to, the second is a referring URL, and the third is user which passes the WP _User object to your function if user is logged in. Otherwise it passes the WP _Error object. Let's take an example in walking through this. We've got our callback function, my_login_redirect, and even though only one of these parameters is required we're actually passing it all three parameters. And this is cool because you can use all of that data within the callback function here to do things.
So for instance here we're using some WordPress conditionals again to determine if user roles are set and if there are user roles we're saying basically if it's an administrator we're just going to send him to the default URL that was already stored in that redirect_to variable. Otherwise we're going to send them to this home URL which is the main page of a WordPress site. So basically if it's an administrator send him one place. If it's any other type of user send him to this home_url and then if we don't know what kind of user it is because a user is not logged in then we'll just return this redirect_to.
So that's the callback function and we're attaching it to this login redirect filter. We've got our default priority of ten and this time instead of that single argument that's the default, we want to pass three arguments back to our callback function. So what we've looked at here are examples of creating custom callback functions and attaching them to WordPress hooks but there will also be times when you utilize callback functions that already exist in WordPress. I should also note that callback functions don't have to be physically located near the hook it's loaded on.
For instance I could have a main plugin page that called all of my hooks such as this add_filter and then a separate page where I actually housed all of my callback functions. However you structure your code is totally up to your preference. It doesn't matter where the callback function is located since it's just sitting there doing nothing until it's called by a hook.
- 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