{"id":135745,"date":"2015-01-07T08:00:19","date_gmt":"2015-01-07T13:00:19","guid":{"rendered":"http:\/\/premium.wpmudev.org\/blog\/?p=135745"},"modified":"2015-12-09T00:59:25","modified_gmt":"2015-12-09T05:59:25","slug":"wordpress-hooks","status":"publish","type":"post","link":"https:\/\/wpmudev.com\/blog\/wordpress-hooks\/","title":{"rendered":"A Quick (and in-Depth) Guide to WordPress Hooks"},"content":{"rendered":"

WordPress hooks are the<\/em> thing to learn if you want to get into WordPress development. Hooks allows you to do two things: change default functionality within WordPress and add your own functionality without modifying core WordPress files at all.<\/p>\n

Making sure you never modify core files is extremely important, but modifying and adding stuff seems impossible without it.<\/p>\n

In this post, I’m going to show you how you can do it pretty easily with two types of hooks: actions and filters. You’ll need a basic understanding of HTML and PHP for this one, but not too much. Let’s dig in!<\/p>\n

The Need for Hooks<\/h3>\n

Hooks are built into\u00a0WordPress and are used to modify or add functionality to the core system. Let’s assume for a moment that WordPress does not provide any hooks. And let’s also say you work with a lot of scheduled posts and you would like to email yourself when a post is published. How would you go about doing that?<\/p>\n

Without hooks you would need to modify core files. You would hunt down the code that is responsible for publishing a post and just after the function that performs the action, you would paste your own code.<\/p>\n

This is detrimental for a number of reasons. The two big ones are updates and uncontrollable code. If you modify core WordPress files your code will work just fine but will be erased when you update WordPress to the next version. You would have to remember or track all of your changes and then put them back in. Not exactly convenient. Alternatively, you could simply not update WordPress, but that would be a huge security risk in the long run.<\/p>\n

Even if you do manage to keep track of changes and update WordPress, you are left with a non-standard environment with uncontrollable code. Other\u00a0WordPress developers will have a hard time dealing with your code, and the community as a whole will not be happy.<\/p>\n

Enter Hooks<\/h3>\n

A hook does almost exactly what we\u00a0talked about\u00a0before (find the place where\u00a0a\u00a0post is published, paste your code), but replaces the horrible pasting bit with a placeholder. By default,\u00a0there is a placeholder after the post publishing function, which allows you to tie functionality there. Here’s a shortened version of the actual wp_publish_post(),<\/code><\/em> which you can find in wp-includes\/post.php<\/a><\/em>.<\/p>\n

Loading gist 61f99825caff867fb22f569fe6e310a9<\/a>

Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

That do_action()<\/code><\/em> bit basically says: You can tie your own function to me, they will all be executed. So whenever WordPress publishes a post using the wp_publish_post()<\/code><\/em> function it goes through all the necessary steps to make it happen. It then moves on to the do_action()<\/code><\/em> function. It’s first parameter is wp_insert_post<\/code><\/em>. Any function which is tied to this wp_insert_post<\/code><\/em> action will get executed.<\/p>\n

Let’s look at an example.<\/p>\n

To create a hooked function you need to create a simple plugin, use your theme’s functions.php<\/em> file, or create a child theme and use the functions.php<\/em> file in there. Let’s create a quick plugin now.<\/p>\n

Create a new folder in the Plugins directory and name it “hook-example.” Create a “hook-example.php<\/em>” file within that directory and paste the following code into it:<\/p>\n

Loading gist d7ccf506f333b4b58c0eb3d29d7344da<\/a>

Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

Your plugin is now ready. Head on over to the Plugins section in\u00a0WordPress\u00a0admin and activate it. Now let’s create a hooked function. In the hook-example.php<\/code><\/em> file, paste the following:<\/p>\n

Loading gist cd4f9ca577b5368ba9341ce256ab7336<\/a>

Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

We’re using the add_action()<\/code><\/em> function to let WordPress know that we’d like to hook a function into wp_insert_post<\/code><\/em>. The second and third parameters are the priority and the arguments. We’ll get into that soon.<\/p>\n

In our hooked function we simply define what we’d like to do. In this case send an email to ourselves. Whenever WordPress published a post it will look for all functions hooked into wp_insert_post<\/code><\/em> and run them all.<\/p>\n

So what have we achieved here? We’ve added functionality to a core part of WordPress without actually modifying the core files. All we needed was one extra line of code. This is very important! All you need to do is write a function that does what you need, then you hook it into a specific part of WordPress.<\/p>\n

Actions and Filters<\/h3>\n

So far we’ve seen what an action is \u2013 it’s a piece of code that\u00a0is executed at a specific time. A filter can be used to modify content before WordPress uses it. You could use a filter to modify the “your password is incorrect” text on the login page. Let’s take a look at wp-login.php<\/code><\/em>:<\/p>\n

Loading gist a9e159b3b44197220ea52052af5e0cf7<\/a>

Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

The snippet from the actual file that handles logins shows that login error messages are displayed using an apply_filters()<\/code><\/em> function. This is very similar in logic to the do-action()<\/code><\/em> function.<\/p>\n

My second parameter contains some sort of data. If you use a hooked function based on my first parameter you can modify this data, otherwise I’m going to use it as is. By default, if you enter a correct username but incorrect password you see the following notice:<\/p>\n

\n
\"Incorrect<\/div>\n<\/div>\n

If you think this is a bit unsafe because it exposes the fact that the username is correct you can hook a function to login_errors<\/code><\/em> to modify it. Here’s how:<\/p>\n

Loading gist ae4a778a1372ed3a2ee48b523cac9534<\/a>

Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

By implementing this change you’ve added a bit more security to your login process and you can also control the text.<\/p>\n

\n
\"Modified<\/div>\n<\/div>\n

Hooks, Actions, Filters, Hooked Function and Tags<\/h3>\n

There is some confusion about these terms above because sometimes they are used interchangeably. I myself mis-speak sometimes, so let’s get things straight just in case I mess up further down!<\/p>\n

Hook<\/strong> is an umbrella term for actions and filters.\u00a0Actions<\/strong> allow you to add your own functionality next to existing functionality. Filters<\/strong> allow you to modify existing functionality. Sometimes the word tag<\/strong> is used to refer to the string that indicates where you are adding your hook. A\u00a0hooked function<\/strong> is\u00a0a\u00a0function you create\u00a0that\u00a0adds or modifies functionality.<\/p>\n

The Anatomy of a Hook<\/h3>\n

When we use hooks we generally rely on two functions: add_action()<\/code><\/em> and add_filter()<\/code><\/em>. Both these function take four parameters:<\/p>\n

    \n
  1. The first parameter is the tag<\/strong>. This is the bit that tells WordPress where to hook your function, when it should be executed.<\/li>\n
  2. The second parameter should be the name of the hooked function.<\/strong><\/li>\n
  3. The third parameter is the priority of the hook<\/strong>. This determines the order in which it is executed if multiple functions are hooked into the same tag.<\/li>\n
  4. The fourth parameter defines the number of parameters passed to this function<\/strong>. By default this is 1, but some tags (like the previous wp_insert_post<\/code><\/em>) can have more.<\/li>\n<\/ol>\n

    Tag<\/h4>\n

    The first parameter of both functions is a simple string that states when the hooked function is executed. There are many, many tags you can use. There are action tags that run when posts are deleted, categories are created, a user is logged in and more. Filter tags are run on messages for custom taxonomies, post title displays, dates and more. The Hooks Reference<\/a> is a good place to start, but sometimes a Google search can be more effective!<\/p>\n

    Note that some tags may be referred to as variable hooks<\/strong>. There is a hook named “{old_status}_to_{new_status}<\/em>” for example. This hook simply means there are a number of hooks defined for combinations. publish_to_trash<\/code><\/em> would run when a publish post is trashed, future_to_draft<\/code><\/em> would run when a scheduled post is set to draft status.<\/p>\n

    Hooked Function<\/h4>\n

    Again, a simple string, which should be the exact name of the function. Since this will be a function name it should contain letters, numbers and underscores only.<\/p>\n

    Take extra care to make this function unique. If you name a function “send_email” it may\u00a0clash with someone else’s function of the same name. It is common practice to prefix function names, something like: my_send_email<\/em>, or wpmudev_send_email<\/em>.<\/p>\n

    I also advise making your function names readable. You could name your function sae()<\/code><\/em>, short for “send author email” but this is extremely bad practice as no one else will know what this means, and you will probably forget in a few months as well.<\/p>\n

    Hook Priority<\/h4>\n

    The third function defines the priority of a hook. The lower the priority the sooner the function gets executed. In some cases the order is not important but in some cases it is essential. If you want to send a post publication email to yourself and the author, the order doesn’t much matter. You can use the default of 10 for both:<\/p>\n

    Loading gist e5361557ee10610034e5ab136343b388<\/a>

    Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

    However, if you would like to update some statistics whenever a post is updated and then notify the author the order suddenly becomes important:<\/p>\n

    Loading gist 9f2c3824f47ed74e7e4903f64bb119ec<\/a>

    Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

    As you can see, the order in which the add_action()<\/code><\/em> calls are places is not important. The second call has a lower priority, therefore it will be executed first.<\/p>\n

    For filters you need to be more careful. Since filters modify data they may overwrite each other. If two filters are hooked into the same tag, the one with the lower priority is executed first. Then, the one with the higher priority is executed which may change the data completely. Many times this is desirable behavior, it’s just something to be aware of.<\/p>\n

    Parameters<\/h4>\n

    The fourth parameter sets the number of parameters passed to our hooked function. This is something you will need to hunt down as it depends on what is in the source code.<\/p>\n

    If you go back to see how we changed the login errors you’ll notice the following function: apply_filters( 'login_errors', $errors )<\/code><\/em>. The first parameter is the tag, the rest are arguments. There is only one here, so one argument is passed to our hooked function.<\/p>\n

    In case of wp_insert_post()<\/code><\/em> you can see the following in the core files: do_action( 'wp_insert_post', $post->ID, $post, true );<\/code><\/em>. The first parameter is the tag, the rest are arguments, so the value here is 3.<\/p>\n

    Our Own Hooks<\/h3>\n

    The great thing about the hooks system is that we can create our own. All we need is the two familiar functions we’ve seen: do_action()<\/code><\/em> and apply_filters()<\/code><\/em><\/p>\n

    Let’s create our own filter for a plugin which displays products. In the footer we could write: “Thanks for using our product display plugin,” which we would allow developers to modify.<\/p>\n

    Here’s how that can be done:<\/p>\n

    Loading gist 60329fe336714600f0e7d68f7ae8eaef<\/a>

    Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

    Actions can be added the same way. You may want to allow users to add some content below the description of a product display:<\/p>\n

    Loading gist 4971d7db22f7af4b09dc47570824631e<\/a>

    Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

    I’ve used the do_action()<\/code><\/em> function to allow others to modify my functionality. I’ve also added the post object as the first parameter, just in case people want to add some post-specific content.<\/p>\n

    Conclusion<\/h3>\n

    In this article we looked at the basics of hooks. We learned the difference between actions and filters and how to use them to effectively change the way WordPress works.<\/p>\n

    We also had a look at how we can add hooks of our own to our plugins and themes. This is immensely useful for making our work developer friendly.<\/p>\n

    Hooks are a part of the Plugin API<\/a>, if you want to learn more about them I suggest reading the relevant pages in the WordPress Codex. The more you use hooks the more you’ll love them and appreciate the power and flexibility they offer.<\/p>\n","protected":false},"excerpt":{"rendered":"

    If you want to get stuck into WordPress development you need to know about hooks, which let you do two things: change default functionality within WordPress, and add your own functionality without modifying core WordPress files.<\/p>\n","protected":false},"author":344049,"featured_media":135957,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"blog_reading_time":"","wds_primary_category":0,"wds_primary_tutorials_categories":0,"footnotes":""},"categories":[263],"tags":[],"tutorials_categories":[],"class_list":["post-135745","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tutorials"],"_links":{"self":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/135745","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/users\/344049"}],"replies":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/comments?post=135745"}],"version-history":[{"count":2,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/135745\/revisions"}],"predecessor-version":[{"id":149967,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/135745\/revisions\/149967"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media\/135957"}],"wp:attachment":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media?parent=135745"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/categories?post=135745"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tags?post=135745"},{"taxonomy":"tutorials_categories","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tutorials_categories?post=135745"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}