Plugin APIG2

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 event based. Each plugin will register to listen for events that are generated by the GL2 kernel and other plugins. The GL2 kernel will act as a router for these events. When an event occurs, the GL2 kernel will call all the plugins that have registered for that event.

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 glPluginInterface {

    /**************************************************
     * Installs and registers the plugin with the GL2 kernel
     *
     * Handles the creation of data structures, security setup, and
     * registers for events.
     *
     * @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 events.
     *
     * @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 events 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();

    /**************************************************
     * Event handler
     *
     * Executes actions based on events passed to the function by the
     * GL2 kernel.
     *
     * @access public
     * @return mixed    return type depends on event
     **************************************************/
    public function handleEvent( $event, $var = '');
}

Events

Registering for Events

When a plugin's install() function is called it is expected to register for all the events it will need to handle. This is accomplished using the function glSetEventWatch(). Similarly within the uninstall() function, the function glUnsetEventWatch() should be used to deregister event watches.

A plugin should never register for its own events as this has the potential to create infinite loops. In any case such a feature should not be needed, as a plugin can execute any required tasks when an event is triggered.

Handling Events

When an event is triggered, either by the GL2 kernel or by a plugin, the handleEvent() function is called on all plugins registered for that event. 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 event in such a way that the handled event is triggered. Infinite loops can avoided in many cases simply by not triggering any events inside the event handler (if possible).

Triggering Events

When a plugin requires input or believes other plugins may benefit from knowing when a certain event occurs, the glTriggerEvent() function should be called.

Event Naming Scheme

Event names should be prefixed with the plugin name. The actual event 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 events triggered exclusively by the GL2 kernel.

Some example event 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)
  • sql (dir)
    • mysql.sql
    • mssql.sql
    • ...
    • updates (dir)
      • mysql_0.1_0.2.sql
      • mssql_0.1_0.2.sql
      • ...

Templates

GL2 will use HTML_Template_Flexy as its template library. Plugins authors are recommended to use this template library as well 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 event handling.

These functions include:

• glSetEventWatch($plugin, $event);
• glUnsetEventWatch($plugin, $event);
• glTriggerEvent($plugin, $event);
• ...many more

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

• A&A
• ...many more

Apendix B: GL2 Core Events

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

Event	Description
core.begin	GL2 begins processing a page request
core.end	GL2 finishes processing a page request
core.adduser	A new user gets added (not self registered)
core.newuser	A new user registers with the site
core.deleteuser	A user account is deleted
core.userprofile.display	Builds the userprofile is display
core.userprofile.update	The userprofile is udpated
core.userlogin	A user logs in
core.userlogout	A user logs out
core.menuitems.display	Builds the header menu items
core.usermenu.display	Builds the user menu display
core.adminmenu.display	Builds the admin menu display
core.searchtypes	Gets available search types
core.search	Performs search
core.admincontrol.display	Builds the administrative display control
core.listsblocks.display	Builds a list of available blocks
core.blocks.display	Builds the blocks for display
core.moderation.list.display	Should we have a moderation plugin? Or should it be part of the core?
core.moderation.display	"
core.moderation.approve	"
core.moderation.delete	"
core.submissioncount	"
core.header.display	Insert javascript/CSS in html <header>

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