WordPress add_action Function [Full Guide]

The add_action function is very popular in the WordPress development world. It can be used to execute custom functions when a predefined event occurs. Today we’re going to take a look at how this function works and some examples of how to use it.

add_action Function Arguments

The function has the following signature:

<?php

function add_action(string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1)

As you can see, it accepts up to 4 parameters, where the first 2 are mandatory and the other 2 are optional:

• $hook_name – the name of the action/hook that our callback will be added to
  
• $callback – the callback that will be run when the action occurs
  
• $priority (optional) – order in which the callback will be run. Lower number is associated with earlier execution
  
• $accepted_args (optional) – the number of args that will be passed to the callback. Default is 1

add_action Function Examples

Now that we know how our function works, let’s take a look at a few examples of how to use the function.

First, let’s start with a basic usage

<?php

add_action('user_register', 'sendNotificationEmail', 10, 2);

function sendNotificationEmail($user_id, $userdata) {
  $user = get_user_by('ID', $user_id);

  if (! $user) {
     return;
  }
  
  wp_mail($user->user_email, 'Welcome!', 'Welcome to our website');
}

In the example below we are sending our user a welcome email when they register. In order to do that, we’re using the user_register action hook which is run whenever a user is registered.

Since the user_register hook passes 2 arguments, we’re passing 2 as the fourth argument in our function.
We could’ve also omitted the 3rd and 4th optional arguments if were only interested in accepting one argument in our function like this:

<?php

add_action('user_register', 'sendNotificationEmail');

function sendNotificationEmail($user_id) {
 // function body
}

Now let’s take a look at how we can use an object method instead of a function as a callback for the hook:

<?php

class Notifications 
{

    public function sendNotificationEmail($user_id, $userdata) 
    {
        $user = get_user_by('ID', $user_id);

        if (! $user) {
           return;
        }
        
        wp_mail($user->user_email, 'Welcome!', 'Welcome to our website');
    }
}

$notifications = new Notifications();

add_action('user_register', [$notifications, 'sendNotificationEmail']);

The code above will create an instance of the Notifications object. Then, we’re passing an array with 2 values as our callback, where the 1st argument is the object instance, and the second is the name of the method we want to run.

Remember that the method we pass always has to be public, otherwise it won’t work.

Difference Between add_action vs add_filter

In fact, these 2 functions are very similar and have the same function signature. The only major difference is that the add_filter and do_filter functions are used when some kind of data needs to be altered (for example, you want to alter validation errors after a form validation), whereas the add_action and do_action functions are triggered after an event has occurred, but they don’t alter any data.

Wrapping Up

As you can see, the add_action function is a great way to hook into different events that WordPress or other plugins might trigger and add additional functionality to the project. Feel free to use it more often whenever you need to add new features to your WordPress site and the plugins that you’re using in your project.