Extending actions

When the Elgg framework calls an action the Action handler triggers a plugin hook called “action” before executing the action itself. This hook looks like this:

   $event_result = true;
   $event_result = trigger_plugin_hook('action', $action, null, $event_result);

Where $action is the action being called. If the hook returns false then the main action will not be executed.

The captcha module uses this to intercept the register and user/requestnewpassword actions and redirect them to a function which checks the captcha code. This check returns true if valid or false if not (which prevents the associated action from executing).

This is done as follows:

   register_plugin_hook("action", "register", "captcha_verify_action_hook");
   register_plugin_hook("action", "user/requestnewpassword", "captcha_verify_action_hook");

   .
   .
   .

   function captcha_verify_action_hook($hook, $entity_type, $returnvalue, $params)
   {
   $token = get_input('captcha_token');
   $input = get_input('captcha_input');

   if (($token) && (captcha_verify_captcha($input, $token)))
   return true;

   register_error(elgg_echo('captcha:captchafail'));

   return false;
   }

This lets a plugin extend an existing action without the need to replace the action itself. In the case of the captcha plugin it allows the plugin to provide captcha support in a very loosely coupled way.