A Quick (and in-Depth) Guide to WordPress Hooks

WordPress hooks are the 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.

Making sure you never modify core files is extremely important, but modifying and adding stuff seems impossible without it.

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!

The Need for Hooks

Hooks are built into WordPress 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?

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.

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.

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 WordPress developers will have a hard time dealing with your code, and the community as a whole will not be happy.

Enter Hooks

A hook does almost exactly what we talked about before (find the place where a post is published, paste your code), but replaces the horrible pasting bit with a placeholder. By default, there 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(), which you can find in wp-includes/post.php.

function wp_publish_post( $post ) {
  // Stuff that actually published the post  
  do_action( 'wp_insert_post', $post->ID, $post, true );
}

That do_action() 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() function it goes through all the necessary steps to make it happen. It then moves on to the do_action() function. It’s first parameter is wp_insert_post. Any function which is tied to this wp_insert_post action will get executed.

Let’s look at an example.

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

Create a new folder in the Plugins directory and name it “hook-example.” Create a “hook-example.php” file within that directory and paste the following code into it:

<?php
/**
 * Plugin Name: Hook Test
 * Description: A simple plugin to test hooks
 */

Your plugin is now ready. Head on over to the Plugins section in WordPress admin and activate it. Now let’s create a hooked function. In the hook-example.php file, paste the following:

add_action( 'wp_insert_post', 'email_post_author', 10, 3 );
function email_post_author( $post_id, $post, $update ) {
  $email = 'mymail@mail.com';
  $subject = 'New Post Published';
  $message = 'A new post was published, use this link to view it: ' . get_permalink( $post->ID );
  wp_mail( $email, $subject, $message );
}

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

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 and run them all.

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.

Actions and Filters

So far we’ve seen what an action is – it’s a piece of code that is 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:

if ( ! empty( $errors ) ) {
	/**
	 * Filter the error messages displayed above the login form.
	 *
	 * @since 2.1.0
	 *
	 * @param string $errors Login error message.
	 */
	echo '<div id="login_error">' . apply_filters( 'login_errors', $errors ) . "</div>\n";
}

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

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:

https://premium.wpmudev.org/blog/wordpress-hooks/