Plugin

A plugin (sometimes called an add-in, or extension) is a PHP script that interacts with FUDforum to provide a certain, usually very specific, function "on demand". For example, to implement new BBcode tags, send new users a welcome PM (private message), authenticate users against an LDAP directory or to check registering users against the BotScout API.

Plugin support was introduced in FUDforum version 2.8.1.

Developing new plugins

To develop a new pluging, create a new *.plugin file in your forum's FUDdata/plugins directory or create a new subdirectory for it. All plugins must implement one or more hooks by writing PHP functions to handle them.

All BBCode plugins should have functions for both BBCODE2HTML (convert the tag to HTML) and HTML2BBCODE (convert the HTML back to a tag).

Authentication plugins should return either 0 (deny access) or 1 (allow access). It is the plugin's responsibility to register users in the FUDforum database and sync their passwords before allowing them through.

Plugins may also have optional pluginname_enable() and pluginname_disable() functions that will be executed when the plugin is either activated or deactivated from the Plugin Manager admin control panel.

WARNING: If you change existing plugins, copy them to new names to prevent subsequent upgraded from overwriting your changes.

Available hooks

FUDforum provides the following hooks. More hooks will be added as and when required:

Example plugins

Implement additional BBcode tags

Here is an example plugin that implements a new [TEST] BBcode tag:

// Initialize plugin
plugin_add_hook("BBCODE2HTML", "plugin_test_tag_to_html");
plugin_add_hook("HTML2BBCODE", "plugin_test_html_to_tag");

// Convert [TEST] to html code (new post submitted)
function plugin_test_tag_to_html($array) {
        list($bbcode) = $array;
        $bbcode = str_replace('[TEST]', 'Test tag expanded', $bbcode);
        return array($bbcode);
}

// Convert html to [TEST] tag (message edited)
function plugin_test_html_to_tag($array) {
        list($bbcode) = $array;
        $bbcode = str_replace('Test tag expanded', '[TEST]', $bbcode);
        return array($bbcode);
}

External authentication

An example authentication plugin, the only allowed userid and password is hard coded as scott/tiger:

plugin_add_hook('AUTHENTICATE', 'plugin_simple_auth');

function plugin_simple_auth() {
	$login    = $_POST['login'];
	$password = $_POST['password'];
	$tbl = $GLOBALS['DBHOST_TBL_PREFIX'];

 	if ($login == 'admin') return 1;	// Always allow admin through.

	if ($login == 'scott' && $password == 'tiger') {	// Is valid user?
 		if (!($usr_d = db_sab('SELECT id, passwd, salt FROM '.$tbl.'users WHERE login='._esc($login)))) {
			// Register as a FUDforum user.
			$uent = new fud_user_reg;
			$uent->users_opt = -1;
			$uent->login = $login;
			$uent->plaintext_passwd = $password;
			$uent->add();
		} else if ( !((empty($usr_d->salt) && $usr_d->passwd == md5($password)) || $usr_d->passwd == sha1($usr_d->salt . sha1($password)))) {
			// Sync password
			$salt = substr(md5(uniqid(mt_rand(), true)), 0, 9);
			$sec_pass = sha1($salt . sha1($password));
			q('UPDATE '.$tbl.'users SET passwd='._esc($sec_pass).', salt='._esc($salt).' WHERE id='.$usr_d->id);
		}
		return 1;	// Allow access.
	}

	return 0;		// Deny access.
}

Optional call-outs

Optional call-outs functions can be coded in *.plugin files. The functions are named plugin_func(), where plugin is the plugin's name.

plugin_info

Return more information about the plugin to the plugin manager. Example:

function ldap_info() {
       return array('name' => 'LDAP Authentication',
                    'desc' => 'Authenticate forum users from an LDAP...',
                    'version' => '1.2');
}

plugin_enable

Check prerequisites and install the plugin (add DB tables, change files). This function should return array($ok, $err) - a success and failure message. Examples:

function ldap_enable() {
       return array(null, 'You cannot enable this plugin');
}

function ldap_enable() {
       return array('Plugin was successfully installed', null);
}

plugin_disable

Deinstall the plugin. This function should return array($ok, $err) - a success and failure message.

plugin_config

Configure the plugin. Display configuration fields and allow the users to change config values.

plugin_check

Checks and maintenance actions to be performed when the forum's Consistency Checker runs. This call-out is available starting from FUDforum 3.0.4.

Also see

• Plugin Manager, part of the Admin Control Panel that allows administrators to activate or deactivate plugins.
• Plugin directory, list of available plugins.

External links

• Wikipedia entry for Plugins