Getting Started

What are Hooks?

Hooks are a way to run your own code within the plugin that alter or extend the functionality without modifying the core files directly. It is highly recommended you utilize hooks before attempting to modify the core files. Modifying core files is risky because you will lose your changes when the plugin updates itself. Hooks solve this problem because your code is located elsewhere and unaffected by VFB Pro’s updates.

Actions

Actions are best described as a callback function, or pieces of code that executes functions at a particular time. When you hook into an action, you are usually adding your code to run inside another function.

Filters

Filters are best described as modifiers. When you hook into a filter, you are usually changing text or replacing specific data with your own.

Defining Your Function

The first step to working with any hook is writing your PHP function that will contain the code you expect to run. These functions will go inside the VFB Pro Hooks plugin.

For example, if you wanted your friends to get an email message whenever a new entry is created, you might define the following function:

function vfbp_email_friends( $entry_ID )  {
    $friends = 'bob@example.org,susie@example.org';
    mail( $friends, 'New Entries', 'We just got new entries for our contest!' );
    
    return $entry_ID;
}

For most hooks, your function should accept a single parameter. Some hooks take more than one parameter -- check the documentation for the hook (if available) or the VFB Pro source code for more information.

Be sure to avoid multiple functions with the same name! PHP does not allow this and will cause your site to cease functioning.

Setup Your Hook

The second step to working with a hook is by registering the action or filter to your function.

add_action

add_action('hook_name','your_function_name',[priority],[accepted_args]);

hook_name. The name of an action hook provided by WordPress, that tells what event your function should be associated with.

your_function_name. The name of the function that you want to be executed following the event specified by hook_name. This can be a standard php function, a function present in the WordPress core, or a function defined by you in the plugin file (such as ‘vfbp_email_friends' defined above).

priority. An optional integer argument used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order added to the action.

accepted_args. An optional integer argument defining how many arguments your function can accept (default 1), useful because some hooks can pass more than one argument to your function.

Return Value. The (optionally modified) value of the first argument passed to the filter function.

add_filter

	add_filter('hook_name','your_filter',[priority],[accepted_args]);

hook_name. The name of a filter hook provided by WordPress, which defines when your filter should be applied.

your_filter. The name of the function that you want to use for filtering. This can be a standard PHP function, a function present in the WordPress core, or a function defined by you in the plugin file.

priority. An optional integer argument that can be used to specify the order in which the functions associated with a particular filter are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.

accepted_args. An optional integer argument defining how many arguments your function can accept (default 1), useful because some hooks can pass more than one argument to your function.

Finishing Up

To complete our hook, we need to register our hook using one of the above functions. In the case of vfbp_email_friends, we will hook into the vfbp_after_save_entry action. Here’s what that will look like:

add_action( 'vfbp_after_save_entry', 'vfbp_email_friends', 10, 2 );

function vfbp_email_friends( $entry_ID, $form_ID )  {
    $friends = 'bob@example.org,susie@example.org';
    mail( $friends, 'New Entries', 'We just got new entries for our contest!' );
    
    return $entry_ID;
}