add_action

Description

Hooks a function on to a specific action. More specifically, this function will run the function $function_to_add when the event $hook occurs. This function is an alias to add_filter().

See Action Reference for a list of action hooks. Actions are (usually) triggered when the eduTrac SIS core calls do_action().

Usage

<?php $app->hook->add_action( $hook, $function_to_add, $priority, $accepted_args ); ?>

Parameters

$hook: (string) (required) The name of the action to which $function_to_add is hooked. (See Action Reference for a list of action hooks).

$function_to_add: (callback) (required) The name of the function you wish to be hooked.

$priority: (int) (optional) Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.

$accepted_args: (int) (optional) The number of arguments the hooked function accepts. Hooked functions can take extra arguments that are set when the matching do_action() or apply_filter() call is run.

Return Values

(bool) Always True.

Example

Simple Hook

Email registrar’s office when a student registers for a course:

$app = \Liten\Liten::getInstance();

function email_registrar($sacd)
{
    $email = _etsis_email();
    
    $registrar = 'registrar@college.edu';
    
    $mail->et_mail($registrar, _t("New Course Registration"), sprintf( _t( 'Student registered for a course. Below are the details <br /><br /> %s' ), var_dump($sacd) ));
}
$app->hook->add_action('post_save_myet_reg', 'email_registrar', 10, 1);

Accepted Arguments

A hooked function can optionally accept arguments from the action call, if any are set to be passed. In above example, the email_registrar function takes the $sacd argument, which is automatically passed to the do_action() call using the post_save_myet_reg hook.

Using with a Class

To use add_action() when your plugin is built using a class, you need to use the array callable syntax. You would pass the function to add_action() as an array, with your object as the first element, then the name of the class method, like so:

class Email_Registrar_Class
{
    public $app;
    
    public function __construct() {
        $this->app = \Liten\Liten::getInstance();
    }
    
    public function email_registrar($sacd)
    {
        $email = _etsis_email();
        
        $registrar = 'registrar@college.edu';
        
        $mail->et_mail($registrar, _t("New Course Registration"), sprintf(_t('Student registered for a course. Below are the details <br /><br /> %s'), var_dump($sacd)));
    }
}

$reg_class = new Email_Registrar_Class();
$reg_class->app->hook->add_action('post_save_myet_reg', [
    $reg_class,
    'email_registrar'
], 10, 1);

If the class method can be called statically, the approach is much like the way you would a function: you can just pass a string with the full method:

$app = \Liten\Liten::getInstance();

class Email_Registrar_Class
{
    public static function email_registrar($sacd)
    {
        $email = _etsis_email();
        
        $registrar = 'registrar@college.edu';
        
        $mail->et_mail($registrar, _t("New Course Registration"), sprintf(_t('Student registered for a course. Below are the details <br /><br /> %s'), var_dump($sacd)));
    }
}
$app->hook->add_action('post_save_myet_reg', 'Email_Registrar_Class::email_registrar', 10, 1);

Notes

To find out the number and name of arguments for an action, you can search the code base for the matching do_action() call. For example, if you are hooking into post_save_myet_reg, you would find it in app/routers/courses.router.php: <?php $app->hook->do_action( 'post_save_myet_reg', $sacd ); ?>. Alternatively, the easier way is to search for the particular action in the Handbook.

Your add_action call would look like: <?php $app->hook->add_action( 'post_save_myet_reg', 'email_registrar', 10, 1 ); ?> 

And your function would be:

function email_registrar( $sacd ) {
   // do stuff here
}

Change Log

Since 1.0.0

Source File

$app->hook->add_action() is located in app/src/Hooks.php.