Callback Hook System

Introduction and Purpose

Version 2.0.0 of Cgiapp2 introduces the callback hook system. This was originally introduced to CGI::Application during the fall of 2004 to provide even more flexibility to the already flexible CGI::Application; standard plugins for handling things such as authorization, form validation, and other template engines can then be developed and plugged into an application at specific points of execution to speed development and also to prevent the need to rewrite superclasses.

The callback hook system implements a classic observer pattern. The object class becomes the subject, and the call_hook() method is used to notify observers. The 'hook' argument to call_hook() indicates the event that has been triggered, which in turn selects which observers to notify. All observers are passed an object instance of the observable class in order to effect its modification.

Callback Hooks

There are several pre-installed Cgiapp2::$_INSTALLED_HOOKS you may tie into. These include:

You may also create your own hooks using new_hook(), allowing other classes the ability to customize your application classes.

To make use of the callback system, you must register callbacks with it. You do so with the add_callback() method, which allows you to register a callback with a hook; additionally, you can prioritize when it is executed by optionally providing a class with which to register it. Those hooks registered with the class of the current object instance are executed first, while those of the class' ancestors getting executed by order of ancestry.

Template hooks (tmpl_path, tmpl_assign, and load_tmpl) are treated slightly differently. The author cannot think of a usage where having multiple template engines present would be a good idea. Additionally, load_tmpl should really only ever return a single string value. As such, the template hooks always register with the Cgiapp2 class, and each callback registered replaces any callbacks previously registered with that hook (i.e., only one callback is allowed per template hook).

API Summary

API Details

All callback hooks are passed at the minimum a single argument, the object instance of the calling class (the observed object). Some hooks take additional arguments:

Additionally, the object instance is typically passed as the first argument to a hook. However, there are some special cases where it is passed as the final argument:

Finally, all callbacks registered with add_callback() must be valid PHP callbacks.

Examples

Below are several examples of callback hooks in use. You may also want to see Cgiapp2_Plugin_Smarty for an example of a class that implements several callback hooks (the template callback hooks).

Example 1: Register a Callback with a Hook

An example of how to register a callback:

class SomeClass
{
    public static function prerunHook($rm, $cgiapp)
    {
        // Don't allow access to admin mode unless user is admin
        if (('admin' != $_SESSION['username'])
            && ('admin' == $rm))
        {
            $cgiapp->prerun_mode('login');
        }}
}
Cgiapp2::add_callback('prerun', array('SomeClass', 'prerunHook'), 'MyCgiapp2');

The above code creates a class, 'SomeClass', that registers a prerun hook with the class 'MyCgiapp2'. If certain conditions are met, it changes the run mode of MyCgiapp2 (or one of its descendents) to 'login'.

Example 2: Create and Implement a Custom Hook

An example of how to create a new hook and register a callback with it:

class SomeClass extends Cgiapp2
{
    protected function cgiapp_init($args, $cgiapp)
    {
        self::new_hook('postTemplate', 'SomeClass');
    }
 
    // some other stuff in between: setup(), run modes, etc.
 
    
    protected function cgiapp_postrun($body, $cgiapp)
    {
        $this->tmpl_assign('content', $body);
        $body = $this->load_tmpl($this->param('site_tmpl'));
        $body = $this->call_hook('postTemplate', $body);
        $cgiapp->postrun_body($body);
    }
}
 
class postClass
{
    function tidy($cgiapp, $body)
    {
        $tidy = new tidy;
        $tidy->parseString($body);
        $tidy->cleanRepair();
 
        return $body;
    }
}
Cgiapp2::add_callback('postTemplate', array('postClass', 'tidy'), 'SomeClass');

The above code creates a class, 'SomeClass', that creates a 'postTemplate' hook; this hook is then called in cgiapp_postrun() after assigning the run mode content to a sitewide template.

A new class, postClass, implements a method 'tidy' that takes some text and runs it through tidy. It is then added as a callback to the 'postTemplate' hook.

In effect, 'SomeClass' has just added a hook for manipulating the final content of the application.

Included Plugins

The Cgiapp2 distribution package includes a number of plugins ready for use: