MyBB Community Forums

Before continuing with this tutorial, it is imperative that you have at least a basic understanding of PHP. There are lots of online tutorials already available to help you learn PHP, such as W3Schools and php.net, however there are lots more too which can be found with a quick search query.

If you are reading this, I will assume you have at least a basic understanding of PHP.

The basic structure of a plugin

Firstly you need to create a new php file. Create a new file in your favourite text editor and Save it as myfirstplugin.php. The filename must be the same as the function name. For example myfirstplugin_something().

Now we are going to start writing the plugin. Firstly create a set of opening and closing php tags and prevent direct initialization of the plugin file for extra security. To do that, we use an if statement to check that it's defined IN_MYBB. If it isn't, it will kill the rest of the script and display the error: "You Cannot Access This File Directly. Please Make Sure IN_MYBB Is Defined."

<?php
if(!defined("IN_MYBB"))
{
    die("You Cannot Access This File Directly. Please Make Sure IN_MYBB Is Defined.");
} 
?>

Now we will create our information function. We put this below the previous code.

function myfirstplugin_info()
{
return array(
        "name"  => "My First Plugin",
        "description"=> "This is my first plugin! :)",
        "website"        => "http://mywebsite.com",
        "author"        => "Vernier",
        "authorsite"    => "http://mywebsite.com",
        "version"        => "1.0",
        "guid"             => "",
        "compatibility" => "16*"
    );
}

name: The plugins name
description: The plugins description
website: The plugins website
author: your name
authorsite: your website
version: The plugins version
guid: (Globally Unique Identifiers) A unique identifier that has been generated for your plugin when you submit it to the MyBB Mods site. If you choose you do not want to submit it to the MyBB mods site, leave this blank. It allows users to check their plugins for updates in the plugin system.
compatibility: for 1.6 series, we use: 16*, for 1.4 series, we use 14*, for all series, we use *.

Now we need to specify what happens when the user activates myfirstplugin from the Admin Control Panel. To do this, we add the activate function below the previous code.

function myfirstplugin_activate() {
global $db;

$myfirstplugin_group = array(
        'gid'    => 'NULL',
        'name'  => 'myfirstplugin',
        'title'      => 'My First Plugin',
        'description'    => 'Settings For My First Plugin',
        'disporder'    => "1",
        'isdefault'  => "0",
    );

global $db; is required as we must add the settings group and settings to the database.
gid: This is the settings Group ID.
name: This is the plugins name.
title: The title of your plugin.
description: The description of your plugin.
disporder: This is the display order of the setting group.
isdefault: This is whether the setting is default or not.

We then need to insert that into our database:

$db->insert_query('settinggroups', $myfirstplugin_group);
 $gid = $db->insert_id();

$db->insert_query('settinggroups', $myfirstplugin_group); is creating a database query which contains two parameters. In this case, these are: 'settinggroups' and $myfirstplugin_group. 'settinggroups' is the table in the database & $myfirstplugin_group was defined here: $myfirstplugin_group = array(
This inserts all of the values in the array into the table 'settinggroups'.
$gid = $db->insert_id(); inserts the gid, which can't be the same as another gid.

We can now create a setting. We will create a simple Enable / Disable this plugin setting.

$myfirstplugin_setting = array(
        'sid'            => 'NULL',
        'name'        => 'myfirstplugin_enable',
        'title'            => 'Do you want to enable My First Plugin?',
        'description'    => 'If you set this option to yes, this plugin be active on your board.',
        'optionscode'    => 'yesno',
        'value'        => '1',
        'disporder'        => 1,
        'gid'            => intval($gid),
    );

sid: This is the setting id. Similar to gid for the group settings.
name: This is the name of the setting.
title: This is the title of the setting.
description: This is the description of the plugin.
optionscode: This is what type of input the setting is. Examples of this is yesno ( yes & no radio buttons) & text (text input)
value: This is the default value of the setting. In optionscode yesno, 1 is yes and 0 is no.
disporder: This is the display order of the setting.
gid: This is the group id of the setting.

Now we need to add this array to the database with the following piece of code:

$db->insert_query('settings', $myfirstplugin_setting);
  rebuild_settings();
}

$db->insert_query('settings',$myfirstplugin_setting); is similar to $db->insert_query('settinggroups', $myfirstplugin_group); in that it has 2 parameters. the parameters for this are 'settings' & $myfirstplugin_setting. 'settings' is the table in which to insert the values & $myfirstplugin_setting was defined here: $myfirstplugin_setting = array(
This inserts all of the values in the array into the table 'settings'.
We then need to rebuild the settings using rebuild_settings();
This rebuilds all of the settings and groups so that people will see them.

Now we need to specify what happens when we disable the plugin. To do this, we use the _deactivate() function, like this:

function myfirstplugin_deactivate()
  {
  global $db;
 $db->query("DELETE FROM ".TABLE_PREFIX."settings WHERE name IN ('myfirstplugin_enable')");
    $db->query("DELETE FROM ".TABLE_PREFIX."settinggroups WHERE name='myfirstplugin'");
rebuild_settings();
 } 

global $db; is required as we're deleting from the database.
$db->query("DELETE FROM ".TABLE_PREFIX."settings WHERE name IN ('myfirstplugin_enable')"); is a query to delete the enable setting we created earlier in this tutorial called myfirstplugin_enable from the settings table.
$db->query("DELETE FROM ".TABLE_PREFIX."settinggroups WHERE name='myfirstplugin'"); is a query to delete the settings group we created earlier in this tutorial called myfirstplugin from the settingsgroups table.
We then need to rebuild the settings with the rebuild_settings(); function.

We then use something called a hook which hooks code into MyBB. You can find a list of all MyBB's hooks here.

To add a hook, we use the following function:

$plugins->add_hook('HOOK_NAME', 'FUNCTION');

This function has two parameters. The first parameter is the hook name. In this tutorial, we'll choose the global_start hook.

The second parameter is the function. In this tutorial, we'll create a function called myfirstplugin_global_start

$plugins->add_hook('global_start', 'myfirstplugin_global_start');

Add hooks before function myfirstplugin_info() (at the top), but after if(!defined("IN_MYBB")).

We then create the function myfirstplugin_global_start with the following code:

function myfirstplugin_global_start(){
global $mybb;

if ($mybb->settings['myfirstplugin_enable'] == 1){
 echo "My first plugin works!";
}
} 

As we're using $mybb, we must add it globally by using global $mybb; otherwise we'll get a "Call to undefined member object" error.
function myfirstplugin_global_start() is the function which is the second parameter in the hook: $plugins->add_hook('global_start', 'myfirstplugin_global_start');
In the code above, we're using an if statement: if ($mybb->settings['myfirstplugin_enable'] == 1). This means if the setting is enabled (remember, 1 means yes, 0 means no), echo "My first plugin works!";

We should have:

<?php
//Disallow direct Initialization for extra security.

if(!defined("IN_MYBB"))
{
    die("You Cannot Access This File Directly. Please Make Sure IN_MYBB Is Defined.");
}

// Hooks
$plugins->add_hook('global_start', 'myfirstplugin_global_start');

// Information
function myfirstplugin_info()
{
return array(
        "name"  => "My First Plugin",
        "description"=> "This is my first plugin! :)",
        "website"        => "http://mywebsite.com",
        "author"        => "Vernier",
        "authorsite"    => "http://mywebsite.com",
        "version"        => "1.0",
        "guid"             => "",
        "compatibility" => "16*"
    );
}

// Activate
function myfirstplugin_activate() {
global $db;

$myfirstplugin_group = array(
        'gid'    => 'NULL',
        'name'  => 'myfirstplugin',
        'title'      => 'My First Plugin',
        'description'    => 'Settings For My First Plugin',
        'disporder'    => "1",
        'isdefault'  => "0",
    );
$db->insert_query('settinggroups', $myfirstplugin_group);
 $gid = $db->insert_id();

$myfirstplugin_setting = array(
        'sid'            => 'NULL',
        'name'        => 'myfirstplugin_enable',
        'title'            => 'Do you want to enable My First Plugin?',
        'description'    => 'If you set this option to yes, this plugin be active on your board.',
        'optionscode'    => 'yesno',
        'value'        => '1',
        'disporder'        => 1,
        'gid'            => intval($gid),
    );
$db->insert_query('settings', $myfirstplugin_setting);
  rebuild_settings();
}

// Deactivate
function myfirstplugin_deactivate()
  {
  global $db;
 $db->query("DELETE FROM ".TABLE_PREFIX."settings WHERE name IN ('myfirstplugin_enable')");
    $db->query("DELETE FROM ".TABLE_PREFIX."settinggroups WHERE name='myfirstplugin'");
rebuild_settings();
 }

function myfirstplugin_global_start(){
global $mybb;

if ($mybb->settings['myfirstplugin_enable'] == 1){
 echo "My first plugin works!";
}
} 
?>

Now Upload this file to ./inc/plugins and then navigate to Admincp -> Configuration -> Plugins -> My First Plugin -> Activate.

You will see if you refresh your forum, it will display a message at the top displaying: My first plugin works!

Now try this; Navigate to Admincp -> Configuration -> Settings -> My First Plugin
set Do you want to enable My First Plugin? to no and click Save Settings. Now refresh your forum. You will notice it's not there anymore. Try re-enabling it. You will notice it's there again. Try deactivate it now. You will notice that the settings and the settings group has been deleted successfully. If you re-enable it, they will be re-added.

I hope you learnt how to author basic plugins from my tutorial above!

If this didn't work for you, post your code below and I'll try find out why

Thanks guys!

Very nice guide this will help new plugin authors for sure!

Thank you

As soon as I'm done learning the basics of PHP, lets see how this goes.
Can't wait for Part 2 though. Nice work Vernier.

Thanks BlackChaos

There are some good tutorials out there for learning PHP, w3schools have some good tutorials. http://www.w3schools.com/php/default.asp

thanks very much

very good explanation for me

Thank you

Great tutorial Guide Vernier, Thank I learn basic!

Thank you, Dragonzsoul!

Yay, it works!

My question though:

If I want to add another setting (which I do), do I simply copy and paste this code, then change it depending on what I want?

$myfirstplugin_setting = array(
        'sid'            => 'NULL',
        'name'        => 'myfirstplugin_enable',
        'title'            => 'Do you want to enable My First Plugin?',
        'description'    => 'If you set this option to yes, this plugin be active on your board.',
        'optionscode'    => 'yesno',
        'value'        => '1',
        'disporder'        => 1,
        'gid'            => intval($gid),
    ); 

And additionally, how would I get it so that whatever I put into a textbox in my plugin's Settings, it would show up? i.e In this example, change "My first plugin works!" to whatever I have inputted into the textbox?