View source for Plugin APIG2

== Introduction ==

Geeklog 2 (GL2) is the next generation of content management systems in the popular [http://www.geeklog.net/ 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 [http://www.zend.com/php5/ PHP 5] and make extensive use of the [http://pear.php.net/ 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:

<pre>
class Geeklog_PluginInterface {

    /**
     * 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
     * @param  string   name of event that requires action
     * @param  mixed    variable type (and existence) dependent on event
     * @return mixed    return type depends on event
     */
    public function handleEvent( $event, $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 );
}
</pre>

== 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 event registration and notification. 

<pre>
class Geeklog_ActionManager {
    /**
    * Array containing event keys and listener (arrays as) values
    * This takes the form of $listeners[<eventName>] = 
    *                             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 event
    *
    * @author Vincent Furia <vfuria@gmail.com>
    * @access public
    * @param  mixed   $event  event(s) to listen for (string or array)
    * @param  string  $plugin plugin to be registered as listener
    * @return boolean true on success
    *
    */
    public function registerListener($events, $plugin) {
        // add the listener to the $listeners variable and the database
    }

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

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

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

== 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 registerListener() of the glEventManager class. Similarly within the uninstall() function, the function unregisterListener() of the glEventManager class 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 (as such the glEventManager 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 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 that a given event has occured, the notify() function of the glEventManager class 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 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 [http://www.tonybibbs.com/staticpages/index.php/MVCnPHP MVCnPHP] ([http://cvs.geeklog.net/cvs.php/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 [http://pear.php.net/manual/en/package.html.html-template-flexy.intro.php 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 event handling.

These functions include:

*...

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

*A&A
*glEventManager
*glLogger
*...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.  

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

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 <span style="color: rgb(153, 0, 0);">red</span> 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 [http://www.geeklog.net/article.php/2004063000385164#comments geeklog.net].
*Version 0.2 (06/30/2004): updated document with comments from [http://www.geeklog.net/forum/viewtopic.php?forum=12&showtopic=34166 geeklog.net], other improvements as needed. Added Apendix with potential plugins.
*Version 0.1 (04/27/2004): initial release of the documentation for comments