add_action – WordPress function to hook on events

add_action is an extremely used WordPress function, constructed using of PHP’s native function call_user_func_array, widely used in WP core, plugin & theme. In other sense, add_action is similar method to JavaScript’s on event binding mechanism – on('event').

If you dig WordPress Core files and see do_action('somethis'), then the ‘something’ is an Action Hook that you can use to do your custom processing using add_action() function. A list of WordPress hooks (Action hooks) reference can be found at Action Reference.

Understanding add_action:

WordPress uses an event binding method, events such as save_post, post_updated, insert_user & lots more. These are called hook or callback. Each of these hook has it’s own definition (you can will find that on WordPress Codex pages). These hooks supply one or multiple variables (values), Like, save_post supply post_id that is being saved right now, delete_post supply post_id what will be deleted right now. These Hooks are used by creating a function and using add_action function with the hook name. Using these hook, you can do your own processing. Ex: you might need to send and email to the site administrator after a post has been saved, or might want to recalculate the social sharing count after post has been updated, and a much more deeper things. I will try to describe a Practical Example.

An Example of add_action:

Goal: Send an email to an user email address upon deleting their account.
Brief: There are two hook WordPress provide us to use upon user account deletion. delete_user – that is fired before deleting everything about an user from database, and deleted_user – that fires after all data regarding that user has been deleted from database. Now, To send the email, we will need to use the first hook ‘delete_user’, because on the second hook deleted_user, user data wont be available on the database. But we will need user email address & that we can get using deleted_user hook.

Code example:

add_action('delete_user', 'myplugin_send_email_before_delete_user');

// this is a custom function that is hooked,
// the $user_id variable on out function will be passed by the delete_user hook.
function myplugin_send_email_before_delete_user($user_id)
{
    // we are querying the user email from database
    $email = get_user_option('user_email', $user_id);

    // ofcourse you can retrieve more user information and add into email
    wp_mail($email, 'You account has been deleted', 'The mail content.');
}

So if you put this code on your plugin or on your active themes functions.php file, an email will be sent to the user, whom account has been just deleted. You can test this by creating an account with your email address and deleting that from the WP Admin -> Users page. You will need to login with an administrator account ofcourse.

If you had a question in mind that how do i know that user_id will be supplied to our function (myplugin_send_email_before_delete_user), the answer is, i read that on the WP Codex page, You can read that also – delete_user.

Custom Hook

Rather than the hook’s WP made available on their framework, we can create additional hook for our own purpose. That is done using do_action(') function. Example: We can add a hook to our function we have created myplugin_send_email_before_delete_user which will allow us or others to add an action on it.

// this is a custom function that is hooked,
// the $user_id variable on out function will be passed by the delete_user hook.
function myplugin_send_email_before_delete_user($user_id)
{
    // we are querying the user email from database
    $email = get_user_option('user_email', $user_id);

    // ofcourse you can retrieve more user information and add into email
    wp_mail($email, 'You account has been deleted', 'The mail content.');

    // the new line we just added
    do_action('myplugin_user_deletion_notified', $user_id);
}

On the code, the last line means we are allowing others to use our custom hook to do something. As like we have used save_post hook, we can now also use the ‘myplugin_user_deletion_notified’ to do some more thing, ex: notify admin about this deletion, check the next example.

Notify Admin Regarding User Account Deletion

add_action('myplugin_user_deletion_notified', 'myplugin_notify_admin_about_deletion');

// the $user_id variable will be passed by the myplugin_user_deletion_notified hook.
function myplugin_notify_admin_about_deletion($user_id)
{
    // we are querying the user name from database
    $user_name = get_user_option('display_name', $user_id);

    // we are querying the admin email from database
    $admin_email = get_option('admin_email');

    // send mail
    wp_mail( 
        $admin_email, 
        'User Account Deleted', // subject
        'Hi Admin, An account has been deleted from the site. User name was - '. $user_name // content
    );
}

I hope you understand the concept of hooks and using add_action().