I was coding WordPress themes for an embarrassingly long time before I fully understood how to use WordPress actions. This is how I wish someone had explained them to me when I was beginning as a developer.
I’m going to walk through this abstractly, not with actual WordPress hooks. The point of this article is to understand what WordPress actions are, why they’re useful, and how to use them.
The WordPress Actions of my Dog
My dog, Sycamore, has a good life. Napping, playing, eating: what’s not to like? Let’s build a schedule of an ordinary day in the life of Sycamore with WordPress actions.
The set-up of the actions will be one action for each hour of the day: 1 – 24. When a page loads, it will run all of the 24 actions one immediately after another.
You generally will not add any do_action() to your theme. This is just for demonstration. The important thing to know here is that every time a page loads, it will run 24 actions: one for each hour of the day. So, go to the page, and it will, run, in order:
do_action('1_oclock');
do_action('2_oclock');
do_action('3_oclock');
// etc, until...
do_action('24_oclock');
Each time one of those actions runs, it looks for anything else hooked into the action with the same name (like, ‘1_oclock’) and then runs that action at that time.
The Schedule
Now that we have our actions for each hour of the day running, we can hook into them to display a schedule of my dog Sycamore’s day.
- 7 o’clock: Wake up, lick people’s faces, go on a walk
- 8 o’clock: Eat
- 9 o’clock: Go to sleep
- 12 o’clock: Wake up, chew on something that she’s not supposed to chew on
- 13 o’clock (1pm): Go to sleep
- 16 o’clock (4pm): Wake up, bark at a squirrel, chase something only discernible to her
- 17 o’clock (5pm): Eat, go on a walk
- 18 o’clock (6pm): Go to sleep
- 21 o’clock (9pm): Wake up, bother the cat, sniff random things all over the house
- 22 o’clock (10pm): Go to sleep
We already have our actions for each hour running (do_action('1_oclock'), etc), so all we have to do is hook into them. When we add an action like ‘Wake up’ into our 7_oclock action, we’re simply saying “When the 7_oclock action fires, run any of our code that is hooked into the 7_oclock action.
In code, using WordPress actions, Sycamore’s schedule above looks like:
// actions at 7_oclock (7am)
add_action('7_clock', 'wake_up');
add_action('7_oclock', 'lick_peoples_faces');
add_action('7_oclock', 'go_on_walk');
// actions at 8_oclock (8am)
add_action('8_oclock', 'eat');
// actions at 9_oclock (9am)
add_action('9_oclock', 'sleep');
// actions at 12_oclock (12pm)
add_action('12_oclock', 'wake_up');
add_action('12_oclock', 'chew_something_not_supposed_to');
// actions at 13_oclock (1pm)
add_action('13_oclock', 'sleep');
// actions at 16_oclock (4pm)
add_action('16_oclock', 'wake_up');
add_action('16_oclock', 'bark_at_squirrel');
add_action('16_oclock', 'chase_something_only_i_detect');
// actions at 17_oclock (5pm)
add_action('17_oclock', 'eat');
add_action('17_oclock', 'go_on_walk');
// actions at 18_oclock (6pm)
add_action('18_oclock', 'sleep');
// actions at 21_oclock (9pm)
add_action('21_oclock', 'wake_up');
add_action('21_oclock', 'bother_cat');
add_action('21_oclock', 'sniff_randomly');
// actions at 22_oclock (10pm)
add_action('22_oclock', 'sleep');
Let’s take a closer look at the 7am section:
// actions at 7_oclock (7am)
add_action('7_clock', 'wake_up');
add_action('7_oclock', 'lick_peoples_faces');
add_action('7_oclock', 'go_on_walk');
At 7am, the first thing Sycamore does is wake up. The 'wake_up' part of add_action('7_oclock', 'wake_up'); is matched to a function of the same name: 'wake_up'. The following `wake_up()` function prints the words “Sycamore wakes up” onto the page:
// output the text 'Sycamore wakes up';
function wake_up() {
echo 'Sycamore wakes up';
}
// add 'wake_up' to the '7_oclock' action
add_action('7_clock', 'wake_up');
// run all 7_oclock actions, including 'wake_up'
// note: you likely will not be adding any do_action statements until you're writing plugins. You're far more likely to use add_action hooks
do_action('7_oclock');
Ordering Actions
Great! Sycamore is awake! But… there are multiple things that are supposed to happen at 7 o’clock. How do we make sure that Sycamore doesn’t somehow lick people’s faces before she wakes up?
We can give each action a priority number, with lower numbers running first. It’s like if you’re waiting in line: if you’re number 1 in line, you’ll go first. The default number for an action is 10. All of the actions above would have a priority of 10, because we didn’t specify any order.
To make sure Sycamore wakes up before doing anything else, we give the 7 o’clock wake up action a priority of 1.
// 1 means it will run before anything else
add_action('7_clock', 'wake_up', 1);
// not having a number means it defaults to a priority of 10
// Sycamore needs a good round of lickin' everyone's faces after waking up
add_action('7_oclock', 'lick_peoples_faces');
// wake up: check
// lick faces: check
// time for a walk!
add_action('7_oclock', 'go_on_walk', 20);
Passing Arguments (values) to Actions
If you have a dog, they might have a similar schedule. Let’s open this up to be available for any dog, not just Sycamore.
To do this, the actions that run needs to know what dog is doing the action. We can do this by setting a PHP variable and passing it to the action function. Let’s go back to our do_action('7_oclock'); where we register the 7_oclock action that makes it available to hook into.
// set the $dog_name to equal 'Sycamore'
$dog_name = 'Sycamore';
// pass $dog_name to our do_action. This makes $dog_name available to the functions that hook into this
do_action('7_oclock', $dog_name);
Now that we have a $dog_name variable, we can access it with our functions:
// $dog_name should equal your dog's name
function wake_up($dog_name) {
// if $dog_name = 'Sycamore';
// it outputs the text 'Sycamore wakes up';
echo $dog_name.' wakes up';
}
// add 'wake_up' to the '7_oclock' action
// 1 = the priority
add_action('7_clock', 'wake_up', 1);
So, if your $dog_name is “Fluffy,” then it would output “Fluffy wakes up.”
Schedules can vary from day to day though. On Saturdays, Sycamore’s walk isn’t at 7am, it’s at 8am. A couple things we’d need to know before we can set the Saturday schedule correctly:
- What day is it?
- How to remove her 7am walk and add it in at 8am.
First, let’s address how to get the $day in there. Back where we set the dog name, let’s add in the $day as well and pass it to the actions.
$dog_name = 'Sycamore';
// this will set $day to be the full name of the current day, like 'Saturday' or 'Sunday'
$day = date('l');
// pass $dog_name and $day to our do_action. This makes $dog_name and $day available to the functions that hook into this
do_action('8_oclock', $dog_name, $day);
Similarly to how action priorities default to 10 (the order that actions run), actions default to only having one variable. Now, since there are two variables ($dog_name and $day), we need to tell our actions that we’re using more than one variable. We’ll add our 8am action and make sure it has access to two variables.
// $dog_name should equal your dog's name
// $day will be the current day of the week
function go_on_walk($dog_name, $day) {
// if $day = 'Monday' and $dog_name = 'Sycamore, it will output: "Monday: Sycamore goes on a walk"
echo $day. ': '. $dog_name.' goes on a walk';
}
// if today is Saturday
if($day === 'Saturday') {
// add 'go_on_walk' to the '8_oclock' action
// 10 = the priority. We have to include it here so that we can also add the '2' for the number of arguments
// 2 = the number of arguments ($dog_name and $day)
add_action('8_oclock', 'go_on_walk', 10, 2);
}
Removing Actions
The last thing we have to do is remove the 7 o’clock action because Sycamore doesn’t go on a walk at 7am and 8am on Saturdays. To do this, we use remove_action(). The one catch here is that we have to use remove_action() after the action we want to remove has already been added, otherwise there’s nothing to remove.
// per usual, go on a walk at 7_oclock
add_action('7_oclock', 'go_on_walk', 10, 2);
// if today is Saturday, add in a walk on the 8_oclock action and remove the 7_oclock walk action.
if($day === 'Saturday') {
// add 'go_on_walk' to the '8_oclock' action
add_action('8_oclock', 'go_on_walk', 10, 2);
// remove the '7_oclock walk. We can do this since it was already added above
remove_action('7_oclock', 'go_on_walk');
}
WordPress Action Summary
We’ve gone over what actions in WordPress are. To summarize in a handy list for review:
- WordPress has actions that run when the code runs the
do_action('action_name')code. - You can add your own actions to run when the
do_action('action_name')runs withadd_action('action_name', 'your_function_name'). - You can change the order of when actions run by passing a priority number like
add_action('action_name', 'your_function_name', 1). 1 means it runs first. 10 is the default priority. - If an action has values/arguments that it passes, you can access those in the function you’re using by adding an argument number. If you need more than one argument (the default number), then you can specify the number of arguments you want. For example, to run get three arguments, you’d use
add_action('action_name', 'your_function_name', 10, 3). - You can remove actions with
remove_action('action_name', 'function_you_want_to_remove'), but the action has to have already been added in order to remove it.
If you have any questions on what WordPress actions are or how to use them, feel free to ask in the comments. I’m planning to write a similar article on WordPress Filters, so be sure to follow me on Twitter if you want to know when I finish it!
Jerry Jones 