Intro to WordPress Plugin Development: Using Actions

If you have been following along with the Intro to WordPress Plugin Development series, you would have just learned about how to use filters in your plugin. Next, we’ll look at actions and how they can be used in your plugin.

What is a WordPress action?

According to the WordPress codex:

Actions are triggered by specific events that take place in WordPress, such as publishing a post, changing themes, or displaying an administration screen. An Action is a custom PHP function defined in your plugin (or theme) and hooked, i.e. set to respond, to some of these events.

So, in more simple terms, an action is an event that occurs in WordPress.

WordPress has a lot of actions that take place during every single page load on your site.

An important distinction between actions and filters is that an action happens at a specific point in time during the page load. After the action happens it won’t happen again until the page is refreshed, or a new page is loaded.

How to interact with WordPress actions

WordPress has a few functions that allow us to interact with actions. Note: there are other action related functions, but these are the most commonly used.

• add_action(): this is used when you want to hook your own function to a specific action
• remove_action(): this is used to remove an existing action
• do_action(): this is used to execute the functions that are hooked to a certain action
• has_action(): checks to see if an action has been registered

Example of using actions in WordPress

One action in WordPress is publish_post. This action, like the name implies, is run every time a post is published. Let’s say we want to email someone any time we publish a post. To do this, we would create a function that will hook into the publish_post action. This way, every time a post is published (i.e. publish_post is run), our function will also run.

Here’s an example of how to email someone every time a post is published on our site.

<?php
function sd_email_post_published_notification( $ID, $post ){
	$to		= array( 'friend1@example.com, friend2@example.com, friend3@example.com' );
	$subject	= 'There is a new post published on my site!';
	$message	= 'Come check out the new post on my site:';
	$message	.= '<a href="' . get_permalink( $ID ) . '">' . $post->post_title . '</a> Written by: ' . $post->post_author;
	wp_mail( $to, $subject, $message );
}
add_action( 'publish_post', 'sd_email_post_published_notification', 10, 2 );

In that example, the three email addresses listed in the $to variable would get emailed a message every time you publish a post.

The add_action line in the example has four components to it:

• ‘publish_post’: This is the action that we are “hooking into”. We are basically saying run our function every time publish_post is run.
• ‘sd_email_post_published_notification’: This is the name of the function we want to run whenever publish_post is run. Note how this matches the function name a few lines above.
• 10: This is the priority that we want to give to our function. It is optional, and it defaults to 10 if you leave it off. Lower numbers correspond with earlier execution. Higher numbers correspond with later execution. So if our function relied on an earlier function to run first, we could set the priority to a higher number, like 20. On the other hand, if another function was dependent on our function, we could set ours to run earlier by setting the priority to a lower number like 1.
• 2: This is the number of arguments that our function accepts. In this case, our function is accepting the arguments $ID and $post. This is also optional, and it will default to 1 if you leave it off. In this case, the publish_post action will send the post ID and the post object to our function. We ended up using both, so our add_action included 2 arguments.

Create your own actions

If you want others to be able to perform a function whenever something happens in your plugin, you can add a simple line of code to let that happen.

<?php
do_action( 'my_action_name' );

Any time this function is run, it will “listen” for any other functions that are trying to hook into my_action_name, and execute the resulting functions.

So, if we wanted to output some text whenever my_action_name is run, we can do so like this.

<?php
function sd_add_text_to_my_action_name(){
	echo 'This is the text I want to add';
}
add_action( 'my_action_name', 'sd_add_text_to_my_action_name' );

While this is a simple example, we could have a function that is much more powerful. We could have a function that accesses the database to update a value. Or it could call other functions, and do just about whatever we want it to do.