An Introduction to WordPress Action Hooks

If you’re going to be doing any level of WordPress development, themes or plugins, you will invariably run into the need to take advantage of the WordPress Action Hook system. But the more I am able to talk to people in the community, the more I realize that people simply don’t understand the concept very well, or at all.

In fact, one of the biggest barriers to using what is referred to as a Theme Framework or creating their own plugins is the fact that they rely heavily on Action Hooks to function properly.

Understanding this concept accelerated my level of development skills immediately after I figured out what hooks were, and how they worked. And today, I want to help you find that path too.

So, What Are WordPress Action Hooks?

This can be a very easy, and a somewhat difficult thing to explain. Action hooks are essentially placeholders. Wherever an action hook is placed, it will execute any code that has been “hooked” to it.

So, let’s try to visualize this with some default WordPress action hooks that are in most themes. You can find wp_head and wp_footer in just about every single theme available, and most people don’t realize these are action hooks. They’re simply placeholders that plugins can use to insert code into the <head> and footer of the theme. Often times, they use these action hooks to insert things like CSS or Analytics code. They create a function that generates the code, and then “hook” that function to either wp_head or wp_footer.

If I could wrap up the concept in one sentence, it would be this: WordPress action hooks are a means of providing a way for other developers to insert their own code in specific locations within your code, in order to change or expand the functionality of your code.

Why Action Hooks Are Necessary

Like any other major piece of software, WordPress evolves. Every few months a new version is released.

Let’s assume that action hooks didn’t exist, but you wanted to change or extend some function of WordPress. In order to do this, you have to modify core WordPress files. And when it comes time to upgrade, you’re left with a choice: do the upgrade and lose all my modifications, or stay with the old version.

But if you use action hooks to modify how WordPress works, you can upgrade knowing that your mods are in a separate file which makes the changes the correct way, and you won’t be in danger of having those mods overwritten during the upgrade.

How Do Action Hooks Work?

Going back to the example of the wp_head and wp_footer actions, let’s assume that you wanted to insert some CSS in your <head> section of your theme so that you can override the link colors.

(don’t worry about the “what” so much. the “how” is much more important here).

The first thing you need to do is create a function that inserts the code. Because action hooks only allow functions to be “hooked” to them, we’ll need to create a function that generates the code:

It’s really not a difficult concept, if you think about it. All you need to do is find an action hook that you want to use to output some code, create a function, and hook the function to that action using the add_action code I gave you above.

As always, be sure any PHP code is placed between opening and closing PHP tags, or it will not execute.

Creating Your Own Action Hooks

While WordPress does provide you with a LOT of action hooks that you can take advantage of, you can create your own too, giving your theme or plugin the same benefit of letting other people make changes to your code, without having to edit your code.

So, if you want to provide an action hook that will execute any functions that are “hooked” to it, just use this code:

<?php do_action('my_action_hook_name'); ?>

Of course, change the my_action_hook_name to something unique that describes the location and/or purpose of the action hook.

And now, anyone can come along and hook their own function to your newly created action hook.

Reader Interactions

Comments

In WordPress it is often better, when you use the function wp_enqueue_style() for add Stylesheet in the head on the site. I think it is important to say this on the example to add css to the head with the hook wp_head.
Thanks for the nice post.

Frank,
Very true. If I were adding a call to a stylesheet or JS file, that’s what I would have done. But since I was inserting raw styles into the <head>, it was better to just hook directly to wp_head. The same would have gone for JS code as well.

The enqueue functions are there, primarily, to avoid duplicate calls to the same file, so using them for raw styles or JS has no more benefit than hooking directly to wp_head.

I think the hardest thing for people to grasp (me included) is how to change the layout of a parent theme using action hooks. Someone (who I am not going to mention) said that most child themes look pretty much exactly like the parent theme. The reason for this is that changing the actual structure (not the link color) is a bit more advanced topic, and one that has yet to be addressed thoroughly.

What I would like to see as a followup is a literal example. Take one of the two major frameworks (thesis or thematic) and completely change the layout to something that could no longer resemble the parent theme. When people realize how flexible these frameworks are, I think people might have their ah ha moment. Most of us are still like, “ok but now what”

That’s a pretty good idea. I’ve got a theme framework that I’ve been working on with over 32 action hooks that I’ll be releasing for beta testing soon. Once that happens, I’ll do plenty of examples on how to change the default structure by using action hooks. I would do it with the other 2 frameworks you mentioned, but I simply don’t know enough about them to do them justice.

I’ll try not to make you wait too long. I want to roll out a developer beta as soon as I can. But I need to finish up the default child theme, and set up a forum to discuss development with everyone, so that we can get it ready for a public release.

The function could be created in your theme’s functions.php file, or in a separate plugin. The Action Hook (the do_action() thing) would need to be placed where you want the action hook to execute, wherever that might be.

Nice article Nathan. Thank you for including my article as a resource. Looking forward to your theme framework. I’m also developing my own framework with bits and pieces of Thematic’s source and I hope to release it prematurely as soon as possible. hahaha. Thanks again.

Another good advantage of using hooks is that you can replace original code with yours.

In that way, when you are developing some code, you store it in a function and just below hooks this function with add_action and just after you call do_action.

A better description for do_action is that it calls all functions that are hooked to it, as if it was a list of functions calls. Doing as I said, your function will be called as if you had called it there.

But the difference of calling a function and using an action hook, aside from the action allowing to call a bunch of functions at once and letting other ppl to call their functions inside your code, is that other ppl can use the remove_action function to remove your original function from being called. And after it, they can develop their own function and add it there, replacing your original function from their, which may be better than yours or just do something differently that fits better their needs.

That’s a tremendous powerful feature!!!

And since you are teaching ppl how to do it, I think it is also important to teach them the importance of using prefixes on our functions (and hooks too!), so that they don’t conflict with others’.