MyBB Documentation

Authoring Plugins

MyBB 1.6 Series EOL – Important Notice

The MyBB 1.6 series reached End-Of-Life on October 1, 2015. The MyBB Group strongly encourages all communities running MyBB 1.6 to upgrade as soon as possible to avoid the possibility of future bugs and/or vulnerabilities. Find out more →

The 1.6 Documentation is no longer maintained and some information may be outdated.

Contents

Introduction

Making a plugin for MyBB is like any other PHP undertaking. It requires knowledge of PHP / mySQL and a fairly decent knowledge of MyBB. The latest release of MyBB includes a sample plugin - Hello World - that shows the basic structure of a typical plugin - you should use this as a guide on how to build your own plugins. If possible, you should always code your plugins in the latest release of MyBB.

If you get stuck making plugins, help is at hand at the Community Forum.

Upgrading Plugins to 1.6

If you're upgrading to 1.6 from a previous version of MyBB, check out the Plugin Upgrade Guide

Upgrading Plugins to 1.4

If you're upgrading to 1.4 from a previous version of MyBB, check out the Plugin Upgrade Guide and Preparing your Plugins for 1.4 from the MyBB Blog. There is also this thread: https://community.mybb.com/thread-24122.html

Requirements

As of 1.4, the names of activation, deactivation and information functions must be in the name of your plugin file (minus the .php extension).

For example if your plugin file was called foo.php, your functions would be called foo_activate, foo_deactivate etc.

Although it's not required, it's a good idea to prefix all your functions with your plugin name; foo_run(), foo_bar(), and so on. This is to avoid conflicts with other plugins.

In 1.4, there were changes to the plugin_info (the function that defined the name, description, author etc. of the plugin). This information is used in the Plugin Manager.

	function hello_info()
	{

	return array(
		"name"		=> "Hello World!",
		"description"		=> "A sample plugin ...",
		"website"		=> "https://www.mybb.com",
		"author"		=> "MyBB Group",
		"authorsite"		=> "https://www.mybb.com",
		"version"		=> "1.0",
		"guid" 			=> "",
		"compatibility"	=> "*"
		);
	}

You can take a look at this information in action by going to your AdminCP, and selecting "Plugins" from the Quick Access Menu on the left. What you won't see there is the guid and compatibility. These are two fields added in 1.4 to make it easier to upgrade between versions.

The guid is a unique identifier that will be generated for the plugin when you upload it into the MyBB Mod Database. By including this in your plugin, MyBB users will be able to instantly check for new versions of your plugin from their AdminCP. You will be given a guid to put in your plugin when you add the plugin into the Database.

The compatibility field tells MyBB which versions it will work on. This adds the ability to stop users from installing or running plugins that won't work with their versions of MyBB. This is in CSV format - for example "141,142,143" (MyBB 1.4.1, 1.4.2 and 1.4.3), "14*" (all versions of MyBB 1.4). Wildcards are supported.

For targeting specific versions of 1.6, the compatibility value needs to be in this format: "1604,1605" (MyBB 1.6.4 and 1.6.5).

Activate, Deactivate, Install and Uninstall Functions

MyBB provides 4 set functions to perform certain actions. The _install function should really modify the database (if your plugin does this) to insert things like settings and new fields in tables. If no install function is included, it is assumed that these modifications are done in the _activate function.

	function hello_install()
	{
		// Things to do when the plugin is installed
	}

The _activate function should do things like template changes, language changes and rebuild functions. If you've inserted settings into the database using the _install function, it's a good idea to run a core MyBB function: rebuild_settings();. This will rebuild all the settings and groups so that people will see them in the AdminCP. When a plugin is first installed, the _activate function is also run.

	function hello_activate()
	{
		// Things to do when the plugin is activated
	}

The _is_installed function checks whether the plugin is actually installed in the database or not. It's a good idea to include this if your plugin modifies the database in some way so that people don't repeatedly install your plugin when really, they don't have to.

	function hello_is_installed()
	{
		global $db;
		if($db->table_exists("hello_world"))
		{
			return true;
		}
		return false;
	}

The above functions obviously help users get your plugin onto their forum. The next functions are also vital to include when making a plugin. These reverse the effects your plugin has done.

When a plugin is deactivated, we use the _deactivate function. This function should be used to remove custom edits made to templates and language files, and disable settings that influence the plugin. This should not remove settings or any information from the database. We remove those things in the _uninstall function.

	function hello_deactivate()
	{
		// Things to do when the plugin is deactivated
		// ... things like template changes, language changes etc....
	}

Only if a user wants your plugin uninstalled should you remove information from the database. This is just in case the user wants to reactivate the plugin in the future, they don't lose any of the information your plugin may have already collected or modified in the database. If a plugin is uninstalled without it being deactivated first, MyBB will automatically run the _deactivate function before the uninstall takes place.

	function hello_uninstall()
	{
		// Things to do when the plugin is uninstalled
		// ... should be reserved for altering the database!...
	}

The Hook System

For your plugin to actually work, you need to "hook" your code into MyBB. This can be done in many places throughout MyBB code.

You can see all the hooks available in MyBB at the MyBB Plugin Hooks page.

For an explaination of the hooks, and how they work, check out The Hook System.

This is just a basic introduction to writing plugins for MyBB. You can read more about making your own plugins on the other articles on the Wiki:

MyBB Customization
Templates/Themes Authoring - Template Management - Theme Management - User-created
Plugins Authoring - Plugin Hooks - Plugin Management - User-created
Translations Language Management - Download
Links MyBB Mods

Edit this page on GitHub