Besides knowing how to register a callback function to a hook,
there are a few other things you need to know about working with hooks in WordPress.
In this lesson, you'll learn about hook priority, hook parameters, and hook order.
Let's start with hook priority.
If you take a look at the documentation for add action,
you will see two additional function parameters after the hook name and callback function.
The third parameter is the hook priority, which is an integer which defaults to 10.
This means that if you register an action in your code without specifying a priority,
it will be registered with a priority of 10.
The addFilter function also has a priority parameter, which works in the same way.
Hook priority allows you to determine the order in which your hook callback is run,
relative to any other hook callbacks that may be registered on the given hook,
either by WordPress Core or other themes or plugins.
Hooks run in numerical order of priority, starting with one.
It's usually safe to leave the priority to the default of 10
unless you specify you want to change the order in which your callback function is run.
For example, in the after setup theme example from the actions lesson,
you may want to make sure that the registered callback function is only run
after any other callbacks registered by WordPress Core or run.
Because WordPress Core registers any hook callbacks with the default priority of 10,
if you specify a priority of 11,
you can make sure that your callback function is run after any Core callbacks have completed.
Alternatively, if you want to make sure the callback is run before WordPress Cores,
you would set a lower priority, say nine.
Often you might see callbacks being registered with a high priority like 99 or 9,999.
This is because the plugin or theme developer in question wants to be sure that this callback
is run after all other callbacks. However, one can never know at what priority other third-party
plugins or themes might register their callbacks. Now let's look at hook parameters.
The fourth parameter in the add action and add filter functions is the number of accepted
arguments the callback function can accept. In order to better understand how this works,
let's look at a content-related filter hook called get the excerpt.
Filter is defined in the WP includes post template dot PHP file inside the get the excerpt function,
which in turn is called from the excerpt function. This function is typically used when displaying
search results where it is useful to show the post excerpt and not the post content.
The apply filters function is registering the filter hook with two variables that are
associated with the filter, the posts post excerpt and the post object. When defining an action or
filter hook, any number of possible arguments can be added. However, the number passed to the accepted
arguments parameter determines how many of them are passed back to the hook callback function.
If you look at the documentation for add filter, for example, you will see that the default value
for number of accepted arguments is one, which means that if you don't specify a value for this
parameter, the first argument will be available to be passed to the callback function. In the
get the excerpt filter, there are two possible variables to be accepted. If you were to register
the callback without setting the number of arguments, only the first will be available
to the callback function, in this case post excerpt. In order to accept more of the available arguments,
you need to specify the number of arguments to accept.
And then you can use the additional argument in your callback function.
Being able to determine which arguments you need for your callback function and setting the number
in the hook registration is a valuable skill. For example, let's say you just wanted to add a simple
piece of text after the excerpt. In this case, you would only need the post excerpt, so you can leave
out the accepted argument setting. Notice how the priority has also been updated. You might do this
because you want to make sure this text is amended after any core filter callbacks assigned to this
filter have been run. Now take a look at the results of a search, and you'll see the verified
by search engine at the end of the excerpt. However, what if you wanted to include something
from the post, say the post title? In this case, you would update your callback to accept both
arguments from the hook to get the post title from the post object. And this is what that would look
like in the search results. You'll also notice that this code is using the same variable names
for the arguments being passed of a callback, in this case post excerpt and post. This is not a
requirement. You can call them anything you want when you register your callback function,
but it does make it easier to remember what each variable is if you name them the same.
Depending on your specific requirements, you may first need to determine which action or
filter is the correct one to use. Fortunately, the WordPress developer documentation has a page on
hooks in the common API section, which contains a list of all action and filter hooks and the order
in which they are run during different requests on a WordPress site. You can use this list to check
when the hook you want to use is run and then use this information to determine if it's the correct
hook for your requirements.