Plugin

From FUDforum Wiki
Revision as of 18:20, 14 January 2014 by Kmoradha (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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.

Contents

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.

Info Symbol 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:

Hook/ Call-out Introduced Description
AUTO_LOGIN 3.0.6 Create new user sessions using external authentication provided by the server, such as Basic Authentication (called prior to the user being shown the login form).
AUTHENTICATE 2.8.1 Authenticate users against an external source like an LDAP directory. Example implementation: Email_login.plugin and Ldap.plugin.
BBCODE2HTML 2.8.1 Convert BBcode tags to HTML (as message gets posted). Example implementation: Youtube_tag.plugin.
CAPTCHA 3.0.0 Define a custom CAPTCHA challenge and response to display instead of the default built-in CAPTCHA. Example implementation: Mathcaptcha.plugin.
CAPTCHA_VALIDATE 3.0.0 Validate the user's response to a CAPTCH challenge in case it wasn't supplied with the CAPTCHA hook.
CACHEGET 3.0.2 Read value from in-memory cache (like APC or MEMCACHE). Example implementation: Apccache.plugin.
CACHESET 3.0.2 Store value into in-memory cache. Example implementation: Apccache.plugin.
COMPILER_EXPAND_TEMPLATE 3.0.2 Modify a template a section before it's written out. Example implementation: Google_adsense.plugin.
COMPILER_FINALIZE_PAGE 3.0.2 Modify a page before it's written out. Example implementation: Google_adsense.plugin.
COMPILER_INJECT 3.0.2 Point where plugins can add HTMP or PHP code. Example implementation: addthis.plugin.
CRON 3.0.2 Perform actions after a cron run. Handy for analysing job output or running additional tasks.
CUSTOM_FIELD_VALIDATE 3.0.2 Validate custom profile fields. Any return value will be shown as an error next to the field.
EMAILCONFIRMED 2.8.1 User confirmed his account after registration. Great for sending a welcome message or PM. Example implementation: Welcome_pm.plugin.
HTML2BBCODE 2.8.1 Convert HTML code to BBcode tags (edit post). Example implementation: Youtube_tag.plugin.
INITUSER 2.8.1 Initialize user session. Great for setting themes based on the browser's language or routing mobile phones to a "lo-fi" theme. Example implementation: Theme_router.plugin.
LOGERR 3.0.2 Alter, suppress or log error messages. Can be used to write messages to the syslog, DB table, file or even mail messages to the webmaster. Example implementation: Syslog.plugin.
POST_BACKUP 3.0.3 Perform actions after a backup is taken. Handy for sending notifications and initiating off-site copies. Example implementations: Ftp_backup.plugin and Dropbox.plugin.
PRE_POST 3.0.4 Perform actions before a message is posted.
POST_POST 3.0.4 Perform actions after a user posted a message.
PREREGISTRATION PRE_REGISTER 2.8.1 3.0.4 Additional checks before allowing a user to register. For example, checks against the Botscout API or assign user an avatar image. Example implementations: Botscout.plugin, Gravatar.plugin.
POST_REGISTER 3.0.4 Perform actions after a user was registered.
PRE_TEMPLATE 3.0.3 Perform actions before a template is called (for example, to start output buffering or route to a different template).
POST_TEMPLATE 3.0.3 Perform actions when a template returns. This is a good place to capture and process its output.

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

Languages
Personal tools