Difference between revisions of "Plugin APIG2"

Latest revision as of 03:37, 23 January 2005

Introduction

Geeklog 2 (GL2) is the next generation of content management systems in the popular Geeklog family. Geeklog is becoming a very popular backend for many sites. However, as development continues in the 1.3.x branch of Geeklog and features continue to be added, several architechural problems have been uncovered. These issues include scalability, performance and weakness is the plugin API.

The goal of the GL2 project is to improve all of these areas. This document draws out the plans for the GL2 plugin API. Until the first official release of GL2, this document can be considered a work in progress. For history details please seen the history section at the end of this document (for releases) or refer to the wiki change log (for a detailed list of changes).

It is especially important to note that it is planned for GL2 to use PHP 5 and make extensive use of the PEAR extenstions to php. These choices, along with a authentication and access engine developed by Tony Bibbs, will shape the implementation of the plugin API.

Plugin Overview

The GL2 plugin architecture will be action based. Each plugin will register to listen for actions that are generated by the GL2 kernel and other plugins. The GL2 kernel will act as a router for these actions. When an action occurs, the GL2 kernel will call all the plugins that have registered for that action.

The Plugin Interface Class

The main component of GL2 plugins will be the plugin interface class. This class will need to be implemented by all GL2 plugins. The interface class is outlined below:

class Geeklog_PluginInterface {

    /**
     * Installs and registers the plugin with the GL2 kernel
     *
     * Handles the creation of data structures, security setup, and
     * registers for actions.
     *
     * @access public
     * @return boolean    true for success, false for failure
     */
    public function install();

    /**
     * Uninstalls and deregisters the plugin with the GL2 kernel
     *
     * Handles the removal of data structures, security setup, and
     * deregisters actions.
     *
     * @access public
     * @return boolean    true for success, false for failure
     */
    public function uninstall();

    /**
     * Upgrades the plugin
     *
     * Handles the update of data structures, security setup, and
     * alters the registered for actions as needed.
     *
     * @access public
     * @return boolean    true for success, false for failure
     */
    public function upgrade();

    /**
     * Gets the plugins version information
     *
     * Gets the plugin version information such as version number,
     * minimum GL2 version, version date, plugin name, and possibly
     * other information such as dependencies.
     *
     * @access public
     * @return version structure
     */
    public function getVersion();

    /**
     * Action handler
     *
     * Executes functionality based on action passed to the function by the
     * GL2 kernel.
     *
     * @access public
     * @param  string   name of action that requires handling
     * @param  mixed    variable type (and existence) dependent on action
     * @return mixed    return type depends on action
     */
    public function handleAction( $action, $var = '');

    /**
     * HTML Page Generation
     *
     * Called by index.php (which is responsible for determining which
     * plugin's getPage to call), this function generates a HTML page 
     * based upon user inputed data ($request).  
     *
     * @access public
     * @param  array     Array of applicable GET and POST variables
     * @return string    HTML of requested page
     */
    public function getPage( $request );
}

Action Manager Class

An instance of the class described below will be created globally by the GL2 core. It will be available to all plugins and is responsible for handling plugin action registration and notification.

class Geeklog_ActionManager {
    /**
    * Array containing action keys and listener (arrays as) values
    * This takes the form of $listeners[<actionName>] = 
    *                             array(<pluginName1>, <pluginName2>, etc);
    */
    private $listeners = array();

    /**
    * Geeklog_ActionManager Constructor
    *
    * @author Vincent Furia <vfuria@gmail.com>
    * @access public
    *
    */
    public function __construct() {
        // fetch registered listeners from database, populate $listeners
    }

    /**
    * Register a plugin to listen for an action
    *
    * @author Vincent Furia <vfuria@gmail.com>
    * @access public
    * @param  mixed   $action  action(s) to listen for (string or array)
    * @param  string  $plugin plugin to be registered as listener
    * @return boolean true on success
    *
    */
    public function registerListener($actions, $plugin) {
        // add the listener to the $listeners variable and the database
    }

    /**
    * Unregister a plugin from listening for an action
    *
    * @author Vincent Furia <vfuria@gmail.com>
    * @access public
    * @param  mixed   $action  action(s) to unregister (string or array)
    * @param  string  $plugin plugin to be unregistered as listener
    * @return boolean true on success
    *
    */
    public function unregisterListener($plugin, $actions = '') {
       // remove the listener for the specified actions from $listeners
       // and the database.  If actions is empty then unregister the plugin 
       // for all actions
    }

    /**
    * Get all the listeners for a specific action
    *
    * @author Vincent Furia <vfuria@gmail.com>
    * @access public
    * @param  string $action  action to get listeners of
    * @return array  array of listeners to action $action
    *
    */
    public function getListeners($action) {
       // remove the listener for the specified actions from $listeners
       //   and the database.
    }

    /**
    * Notify listener(s) that an action has occurred
    *
    * @author Vincent Furia <vfuria@gmail.com>
    * @access public
    * @param  mixed $action  action requiring notification
    * @param  mixed $vars   action specific variables
    * @param  mixed $plugin NOTIFY_ALL, specific plugin, or array of plugins
    * @return mixed action specific return values (or array of)
    *
    */
    public function notify($action, $vars, $plugin = NOTIFY_ALL) {
        // call the handle action function for each plugin listening to the
        // relevant action (or, if $plugin specified, only that plugin)
    }


    /**
    * Creates a plugin and returns it
    * 
    * @author Tony Bibbs <tony@geeklog.net>
    * @access public
    * @param string $pluginName Name of the plugin to create
    * @return object An instance of the given plugin name
    *
    */
    private function &getPlugin($pluginName) {
        // creates a instance of a plugin so the plugin can be referenced
        // by other functions in this Class (i.e. notify).
    }
}

Actions

Registering for Actions

When a plugin's install() function is called it is expected to register for all the actions it will need to handle. This is accomplished using the function registerListener() of the Geeklog_ActionManager class. Similarly within the uninstall() function, the function unregisterListener() of the Geeklog_ActionManager class should be used to deregister action watches.

A plugin should never register for its own actions as this has the potential to create infinite loops (as such the Geeklog_ActionManager class will prevent such registrations). In any case such a feature should not be needed, as a plugin can execute any required tasks when an action is triggered.

Handling Actions

When an action is triggered, either by the GL2 kernel or by a plugin, the handleAction() function is called on all plugins registered for that action. At that point it is the responsiblitiy of the plugin to do any required processing and to return an appropriate value.

Each plugin will be responsible for preventing infinite loops caused by handling an action in such a way that the handled action is triggered. Infinite loops can avoided in many cases simply by not triggering any actions inside the action handler (if possible).

Triggering Actions

When a plugin requires input or believes other plugins may benefit from knowing that a given action has occured, the notify() function of the Geeklog_ActionManager class should be called.

Action Naming Scheme

Action names should be prefixed with the plugin name. The actual action name should be descriptive and may contain subnames seperated by a period ('.'). The word 'core' cannot be used as the plugin name as it is resevered for actions triggered by the GL2 kernel.

Some example action names:

• "links.delete" -- triggered when a link from the links plugin is deleted
• "core.userlogin" -- triggered by the GL2 kernel when a user logs in
• "core.userprofile.update" -- triggered by the GL2 kernel when a user profile is updated

Plugin Framework

It is recommended that all plugins be implemented using the MVCnPHP (cvs) class developed by Tony Bibbs. Each plugin will have its own controller and its own set of views and commands.

Directory Structure

All of the files for a plugin are to be kept in a single sub directory of the GL2 plugin directory. The plugin's internal directory structure is based on the MVC framework. The file structure within the plugin directory should look approximate this:

• <plugin name> (dir)
  • commands (dir)
    • <command1>.class.php
    • <command2>.class.php
    • ...
  • views (dir)
    • <view1>.class.php
    • <view2>.class.php
    • ...
    • templates (dir)
      • default (dir or softlink)
      • <layout1> (dir)
      • <layout2> (dir)
      • ...
  • index.php (controller)
  • mvcconfig.php
  • config.php
  • main.class.php (implemented interface class)
  • includes (dir)
  • sql (dir)
    • mysql.sql
    • mssql.sql
    • ...
    • updates (dir)
      • mysql_0.1_0.2.sql
      • mssql_0.1_0.2.sql
      • ...

Function Naming Conventions

To prevent clashes within the namespace (two functions or classes with identical names will cause an error in PHP), the names of all classes and all functions not contained within a class should be prefixed with the plugin's name.

Templates

GL2 will use HTML_Template_Flexy as its template library. Plugins authors are recommended to use this template library for efficiency and consistency.

Logging

Logging will be handled using PHP's built in logging functionality. Specifically, use the trigger_error() function to log errors and messages. Error number constants include: FATAL, ERROR, WARNING, INFO, and DEBUG.

Apendix A: Helper Functions

The GL2 kernel will provide a set helper functions to the plugins. These helper functions will provide functionality in areas such as access and authentication (A&A), search, comments, and action handling.

These functions include:

• ...

In addition, GL2 plugins will have access to the following global classes:

• A&A
• Geeklog_ActionManager
• glLogger
• ...many more

Apendix B: GL2 Core Actions

The following actions will be triggered by the GL2 kernel. They are known as core actions because they exist independent of any installed plugins.

Some items that are currently handled by Geeklog's 1.3.x plugin system will be implmented as a plugin. This includes items such as the "What's New Block", statistics, and the handling of RSS Feeds.

Apendix C: Potential Plugins

Below are two lists indicating an initial ideas for plugins that could be created for GL2. This list is in no way comprehensive. The categories of Application Plugin and Helper plugin are arbitrary and will not effect how the plugins are created or run. Plugins highlighted in red indicate features that are currently implemented in the base Geeklog 1.3.x branch.

Application Plugins

• Articles
• Links
• Calendar
• Polls
• Staticpages
• File Management
• Forum
• Gallery
• Contacts
• E-Commerce
• Quote of the Day
• Blog/Journel
• Webmail
• Stats/System Status

Helper Plugins

• Cron -- execute delayed/timed events
• Moderation? -- administer moderation of plugin items
• Configuration? -- web based method for changing plugin configuration
• RSS/RDF Feeds -- xml content syndication
• What's New -- shows recently updated/added content

Apendix D: Example

An example plugin is in the works (or will be soon).

Apendix E: Document History

• Version 0.3 (08/07/2004): reformated for the wikit and incorporated comments from geeklog.net.
• Version 0.2 (06/30/2004): updated document with comments from geeklog.net, other improvements as needed. Added Apendix with potential plugins.
• Version 0.1 (04/27/2004): initial release of the documentation for comments