MyBB Tutorials
[MyBB] Plugin Basics
Submitted by Akay, 06-05-2015, 05:53 PM, Thread ID: 3558
Thread Closed
Plugins allow you to easily extend or modify MyBB in a modular way, such that changes can easily be activated, deactivated, installed or uninstalled. You can also safely replace the core MyBB files during upgrades without fear of losing your modifications, therefore it is strongly recommended that any changed to the default MyBB functionality be done via the plugin system rather than modifying files.
Developing plugins requires a sound knowledge of PHP, SQL and enough knowledge of MyBB to navigate the core files so that you can find answers in the source code. If you require help please don't hesitate to post in the plugin development section of the community forums.
Plugin basics
Firstly, you must pick a short lowercase string to name your plugin file and use in some of your plugin function names. This string should be unique and relevant to your plugin, for the sake of this example we'll use "myplugin".
Create a PHP file for your plugin at
and name it according to the above, for example
.
Start by putting the following code into your plugin file:
The functions listed above must be prefixed with the name of the plugin file. Therefore you should replace
with the name of your plugin file, for example
should be called
if your plugin file was named
.
The
function is the only required function, however you should ensure any changes made by install or activate are undone in uninstall or deactivate respectively. For example if you create a table in
you should remove that table in
.
Complete the body of the functions in your plugin file as required:
Returns an array of information about the plugin:
N.B.
The codename is the same as the plugin name used to prefix the functions. A good way to have it is to use the following code:
Called whenever a plugin is installed by clicking the "Install" button in the plugin manager.
If no install routine exists, the install button is not shown and it assumed any work will be performed in the _activate() routine.
It is common to create required tables, fields and settings in this function.
Called on the plugin management page to establish if a plugin is already installed or not.
This should return TRUE if the plugin is installed (by checking tables, fields etc) or FALSE if the plugin is not installed.
It is common to use the existence of a table or setting created in the
function to determine whether the plugin is installed or not, for example this is a common implementation assuming a table called
is created:
Called whenever a plugin is to be uninstalled. This should remove ALL traces of the plugin from the installation (tables etc). If it does not exist, uninstall button is not shown.
Called whenever a plugin is activated via the Admin CP. This should essentially make a plugin "visible" by adding templates/template changes, language changes etc.
Called whenever a plugin is deactivated. This should essentially "hide" the plugin from view by removing templates/template changes etc. It should not, however, remove any information such as tables, fields etc - that should be handled by an
routine. When a plugin is uninstalled, this routine will also be called before
if the plugin is active.
Plugin hooks
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 find a list of hooks here, alternatively you can run the following command on a *nix system in a MyBB directory:
Basic usage
First add the hook by putting the following code above the
function near the top of your plugin file:
Where
is the name of the hook you wish to use and
is the name of a function in your plugin that will be run every time this hook is called.
Note, it must be a function name, you shouldn't actually call the function here.
Here is an example which used the
hook and calls the
function:
Now you can implement the function you specified, this function must be either in your plugin file or included by your plugin.
For example, if I defined the following function in my plugin file it would be called every time
is called:
To achieve most things you'll need to interact with the MyBB global variables such as
, etc.
For example, this would test if the current user is an Admin:
Hooks with arguments
Some hooks also pass a value relevant to the location where it's called, these hooks are added the same way except you must add an argument to your plugin function. In some cases you must also return that value (which your plugin may have modified).
Here is an example of two hooks:
And two associated plugin functions, the first modifies the content of
and returns it, the second modifies a value passed by reference.
You'll need to check the context where the hook is called to determine whether it is necessary to return the argument back, or whether it should be modified by reference.
Other hook options
There are two other optional arguments which can be passed to
: priority and file.
For example:
The priority takes into effect if there are two or more functions that are associated with a hook. A lesser value in the priority parameter will mean the function will be executed before the other function(s) with a higher value priority (for example, a priority "0" will execute before "10"). The default priority is 10. Usually you will not need to use this parameter unless you have two plugins that conflict with each other on one hook.
The filename in the file parameter will be "included-once" when the hook is run, before the function is executed.
Plugin Settings
Plugins can create settings which integrate with the "Configuration" tab of the ACP. General plugin options should be implemented using this method to ensure consistency between plugins.
Settings are usually added and removed in the
and
methods respectively, this way the plugin can be deactivated without losing the settings.
Adding settings
To create settings you must first create a group and get it's ID:
Now you can add some settings:
The following setting field type (aka. optionscode) values are supported:
If you were to install the plugin you'd now see your new settings group and settings group in the "Configuration" tab of the ACP.
You can access these values via
, for example
.
Removing settings
If you add settings in your
function you must also remove them in your
function.
Here is an example of removing the above settings:
Using settings for
You may wish to use one of your settings to implement the
function, here is such an example:
Developing plugins requires a sound knowledge of PHP, SQL and enough knowledge of MyBB to navigate the core files so that you can find answers in the source code. If you require help please don't hesitate to post in the plugin development section of the community forums.
Plugin basics
Firstly, you must pick a short lowercase string to name your plugin file and use in some of your plugin function names. This string should be unique and relevant to your plugin, for the sake of this example we'll use "myplugin".
Create a PHP file for your plugin at
Code:
inc/plugins
Code:
inc/plugins/myplugin.php
Start by putting the following code into your plugin file:
PHP Code:
<?php
// Disallow direct access to this file for security reasons
if(!defined("IN_MYBB"))
{
die("Direct initialization of this file is not allowed.");
}
function myplugin_info()
{
return array(
"name" => "",
"description" => "",
"website" => "",
"author" => "",
"authorsite" => "",
"version" => "1.0",
"guid" => "",
"codename" => "",
"compatibility" => "*"
);
}
function myplugin_install()
{
}
function myplugin_is_installed()
{
}
function myplugin_uninstall()
{
}
function myplugin_activate()
{
}
function myplugin_deactivate()
{
}
?>
The functions listed above must be prefixed with the name of the plugin file. Therefore you should replace
Code:
myplugin
Code:
myplugin_info
Code:
foobar_info
Code:
foobar.php
The
Code:
_info()
Code:
_install()
Code:
_uninstall()
Complete the body of the functions in your plugin file as required:
Code:
_info()
Returns an array of information about the plugin:
- name: The name of the plugin
- description: Description of what the plugin does
- website: The website the plugin is maintained at (Optional)
- author: The name of the author of the plugin
- authorsite: The URL to the website of the author (Optional)
- version: The version number of the plugin
- guid: Unique ID issued by the MyBB Mods site for version checking (Obsolete, prefer codename)
- codename: Unique codename of the plugin in the mods section
- compatibility: A CSV list of MyBB versions supported. Ex, "121,123", "12*". Wildcards supported.
N.B.
The codename is the same as the plugin name used to prefix the functions. A good way to have it is to use the following code:
PHP Code:
$codename = str_replace('.php', '', basename(__FILE__));
Code:
_install()
Called whenever a plugin is installed by clicking the "Install" button in the plugin manager.
If no install routine exists, the install button is not shown and it assumed any work will be performed in the _activate() routine.
It is common to create required tables, fields and settings in this function.
Code:
_is_installed()
Called on the plugin management page to establish if a plugin is already installed or not.
This should return TRUE if the plugin is installed (by checking tables, fields etc) or FALSE if the plugin is not installed.
It is common to use the existence of a table or setting created in the
Code:
_install()
Code:
my_plugin
PHP Code:
function myplugin_is_installed()
{
global $db;
if($db->table_exists("my_plugin"))
{
return true;
}
return false;
}
Code:
_uninstall()
Called whenever a plugin is to be uninstalled. This should remove ALL traces of the plugin from the installation (tables etc). If it does not exist, uninstall button is not shown.
Code:
_activate()
Called whenever a plugin is activated via the Admin CP. This should essentially make a plugin "visible" by adding templates/template changes, language changes etc.
Code:
_deactivate
Called whenever a plugin is deactivated. This should essentially "hide" the plugin from view by removing templates/template changes etc. It should not, however, remove any information such as tables, fields etc - that should be handled by an
Code:
_uninstall
Code:
_uninstall()
Plugin hooks
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 find a list of hooks here, alternatively you can run the following command on a *nix system in a MyBB directory:
Code:
grep -inr '$plugins->run_hooks' ./
Basic usage
First add the hook by putting the following code above the
Code:
_info()
PHP Code:
$plugins->add_hook('<hook name>', '<function name>');
Where
Code:
<hook name>
Code:
<function name>
Note, it must be a function name, you shouldn't actually call the function here.
Here is an example which used the
Code:
index_start
Code:
do_something()
PHP Code:
$plugins->add_hook('index_start', 'do_something');
Now you can implement the function you specified, this function must be either in your plugin file or included by your plugin.
For example, if I defined the following function in my plugin file it would be called every time
Code:
index_start
PHP Code:
function do_something()
{
// Do whatever you want here
}
To achieve most things you'll need to interact with the MyBB global variables such as
Code:
$mybb, $user, $db
For example, this would test if the current user is an Admin:
PHP Code:
function do_something()
{
global $mybb;
if($mybb->usergroup['cancp'] == 1)
{
// Admin only
} else {
// Everyone else
}
}
Hooks with arguments
Some hooks also pass a value relevant to the location where it's called, these hooks are added the same way except you must add an argument to your plugin function. In some cases you must also return that value (which your plugin may have modified).
Here is an example of two hooks:
PHP Code:
$plugins->add_hook("pre_output_page", "hello_world");
$plugins->add_hook("postbit", "hello_world_postbit");
And two associated plugin functions, the first modifies the content of
Code:
$content
PHP Code:
function hello_world($page)
{
// This will add Hello World to the top of pages
$page = str_replace(
'<div id="content">',
'<div id="content"><p>Hello World!</p>',
$page
);
return $page;
}
function hello_world_postbit(&$post)
{
// This will add Hello World to the top of all posts
$post['message'] = '<strong>Hello world!</strong><br />' . $post['message'];
}
You'll need to check the context where the hook is called to determine whether it is necessary to return the argument back, or whether it should be modified by reference.
Other hook options
There are two other optional arguments which can be passed to
Code:
$plugins->add_hook()
For example:
PHP Code:
$plugins->add_hook('<hook name>', '<function name>', '<priority>', '<file>');
// With values
$plugins->add_hook('index_start', 'do_something', 5, 'anotherfile.php');
The priority takes into effect if there are two or more functions that are associated with a hook. A lesser value in the priority parameter will mean the function will be executed before the other function(s) with a higher value priority (for example, a priority "0" will execute before "10"). The default priority is 10. Usually you will not need to use this parameter unless you have two plugins that conflict with each other on one hook.
The filename in the file parameter will be "included-once" when the hook is run, before the function is executed.
Plugin Settings
Plugins can create settings which integrate with the "Configuration" tab of the ACP. General plugin options should be implemented using this method to ensure consistency between plugins.
Settings are usually added and removed in the
Code:
_install()
Code:
_uninstall()
Adding settings
To create settings you must first create a group and get it's ID:
PHP Code:
global $db, $mybb;
$setting_group = array(
'name' => 'mysettinggroup',
'title' => 'My Plugin Settings',
'description' => 'This is my plugin and it does some things',
'disporder' => 5, // The order your setting group will display
'isdefault' => 0
);
$gid = $db->insert_query("settinggroups", $setting_group);
Now you can add some settings:
PHP Code:
$setting_array = array(
// A text setting
'fav_colour' => array(
'title' => 'Favorite Colour',
'description' => 'Enter your favorite colour:',
'optionscode' => 'text',
'value' => 'Blue', // Default
'disporder' => 1
),
// A select box
'green_good' => array(
'title' => 'Is green good?',
'description' => 'Select your opinion on whether green is good:',
'optionscode' => "select\n0=Yes\n1=Maybe\n2=No",
'value' => 2,
'disporder' => 2
),
// A yes/no boolean box
'enable_lasers' => array(
'title' => 'Enable lasers?',
'description' => 'Do you want the lasers turned on?',
'optionscode' => 'yesno',
'value' => 1,
'disporder' => 3
),
);
foreach($setting_array as $name => $setting)
{
$setting['name'] = $name;
$setting['gid'] = $gid;
$db->insert_query('settings', $setting);
}
// Don't forget this!
rebuild_settings();
The following setting field type (aka. optionscode) values are supported:
- text : A regular text box
- numeric : A numeric field
- textarea : A larger text box
- yesno : A boolean yes/no control
- onoff : A boolean on/off control
- select : A select box (in the format select followed by = with one per newline)
- radio : A set of radio buttons (in the format select followed by = with one per newline)
- checkbox : A boolean checkbox field
If you were to install the plugin you'd now see your new settings group and settings group in the "Configuration" tab of the ACP.
You can access these values via
Code:
$mybb->settings['<setting name>']
Code:
$mybb->settings['enable_lasers']
Removing settings
If you add settings in your
Code:
_install()
Code:
_uninstall()
Here is an example of removing the above settings:
PHP Code:
global $db;
$db->delete_query('settings', "name IN ('fav_colour','green_good','enable_lasers')");
$db->delete_query('settinggroups', "name = 'mysettinggroup'");
// Don't forget this
rebuild_settings();
Using settings for
Code:
_is_installed()
You may wish to use one of your settings to implement the
Code:
_is_installed()
PHP Code:
global $mybb;
if(isset($mybb->settings['green_good']))
{
return true;
}
return false;
Users browsing this thread: 1 Guest(s)