Thread Rating:
  • 4 Votes - 3.75 Average
  • 1
  • 2
  • 3
  • 4
  • 5
 Quick tutorial on making MyBB plugins
ZiNgA BuRgA Offline
Fag
*******
Posts: 3,357
Joined: Jan 2008
Post: #1
Quick tutorial on making MyBB plugins
If you're reading this, I'm presuming you're interested in developing MyBB plugins or modifications.
I will try to provide a crash course for doing so.

Requirements
If you're administering a forum, I highly suggest you have HTML knowledge, and knowledge of CSS (style) is highly recommended.  So for the rest of this guide, I'm going to presume you know HTML and CSS.  For those who don't know HTML/CSS, it's probably about time to learn the basics of both, at the very least, even if you don't plan on developing plugins.
FYI, HTML is quite similar to bbCode, so if you know how bbCode works, adopting to HTML should be easy.

Apart from that, knowledge of PHP is crucial to developing plugins.  Knowledge of Javascript is also recommended, but not required.

Learning PHP (no previous programming experience)
If you don't know PHP, there's plenty of guides across the internet.  Here's a few:
  • (Official?) Introduction to PHP - A Simple Tutorial - A very basic guide outlining what you need to do, and get familiar with PHP.  Note that the guide is extremely basic, and I wouldn't consider it enough for developing plugins/modifications
  • Introduction to PHP - You can skip some of the steps, as you should already have a webserver set up.  The guide seems to be a decent overview of the basics of PHP.   If you read through this guide (PHP Basic section, PHP Advanced, you can leave till later), you should have sufficient knowledge to start writing some basic scripts.
There are plenty more tutorials across the internet, so if the above two aren't suffice, feel free to Google your own.

(for those with previous programming experience)
Personally, I find PHP one of the simplest languages.  The syntax of PHP is very similar to Perl/C.  If you have experience with any of the previous two, or any language which follows C syntax (C++, Java, Javascript etc) PHP should be much easier to pick up.
I would suggest skimming over the tutorials posted above, or just look at some PHP scripts and try to figure out how they work (this is what I did, basically).
One thing to keep in mind, if you're had little scripting experience (but more on the programming side), is that PHP is a scripting language, and thus, has some different capabilities to compiled languages.  For example, variable and function names actually make sense at runtime, allowing stuff like the eval() function.

So now I know PHP...
Great!  You've completed probably one of the biggest hurdles - commitment.  However, utilizing your newly learnt language may prove to be a little tricky at first.  As long as you stay committed, however, you should be able to overcome these issues.

Basics of a MyBB plugin
Assuming you know PHP, I'm going to jump straight into developing MyBB plugins (rather than modifying MyBB code).
Developing plugins is perhaps more difficult than modifying MyBB code, however, since most additions to MyBB come through plugins, we may as well start there.

The Basic Idea
PHP allows PHP script to include other PHP scripts (for those who have followed the above tutorial, and haven't read the PHP Advanced section, you may want to read about including here).
Plugins are typically uploaded to the /inc/plugins folder, and MyBB will include any active plugins on every page load.  This allows you to execute your own PHP code on every page.
However, this may not seem too useful - most of the time, you only want to run some code at certain points in MyBB, ie, perhaps run something when a user registers.
For this reason, MyBB provides a hook system.  Hooks allow you to insert code at various points in the code.  Note that, however, the number of available hooks is specified by MyBB's sprinkling of hooks throughout the code.
We won't go into the details of how hooks work - basically, we'll assume they are there and work well.

Mandatory Plugin Functions
In addition to the above model, there's a few other things a plugin must handle.  One is to report information about itself to MyBB, so that MyBB can display the plugin in the plugin editor.  This is actually the only mandatory part in any plugin.  The information is declared to MyBB by your plugin defining an _info() function, which should return an array containing the details of your plugin.
There are also two optional functions a plugin may declare, an _activate() and a _deactivate() function which define what is executed when the plugin is activated or deactivated via the AdminCP.

Basic Structure
Here's a minimal plugin (which does nothing) - as you can see, the only required thing is the _info() function.

PHP Code:
1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
function firstplugin_info()
{
	return array(
		'name'			=> 'My First Plugin',
		'description'	=> 'A plugin which does nothing.',
		'website'		=> 'http://',
		'author'		=> 'ME!!!',
		'authorsite'	=> 'http://',
		'version'		=> '1.0'
	);
}
?>

If you've read enough PHP, you should be able to recognize most of the above constructs.  We have declared a function, and the function returns a value - in this case, an array, containing the details of the plugin.  Note that the keys of the array are predefined - you generally shouldn't change them.
If you save the above code to /inc/plugins/firstplugin.php, it should show up in the AdminCP, with the details you specified.
Note, the filename and the prefix to the functions are important.  In the above, since the filename as firstplugin (we ignore the .php extension), the Info function must be named firstplugin_info.

Okay, the above plugin wasn't very exciting - let's look at a plugin which actually does more.

MyBB's Hello World
This plugin is something provided by MyBB to give a demonstration of the plugin system, but will serve our purposes of demonstration here.
Open up /inc/plugins/hello.php.  You should see the following:

PHP Code:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
<?php
/**
 * MyBB 1.2
 * Copyright © 2006 MyBB Group, All Rights Reserved
 *
 * Website: http://www.mybboard.net
 * License: http://www.mybboard.net/eula.html
 *
 * $Id: hello.php 2932 2007-03-10 05:48:55Z chris $
 */

// Disallow direct access to this file for security reasons
if(!defined("IN_MYBB"))
{
	die("Direct initialization of this file is not allowed.<br /><br />Please make sure IN_MYBB is defined.");
}

$plugins->add_hook("pre_output_page", "hello_world");
$plugins->add_hook("postbit", "hello_world_postbit");

function hello_info()
{
	return array(
		"name"			=> "Hello World!",
		"description"	=> "A sample plugin that prints hello world and changes the content of each post to 'Hello world!'",
		"website"		=> "http://www.mybboard.net",
		"author"		=> "MyBB Group",
		"authorsite"	=> "http://www.mybboard.net",
		"version"		=> "1.0",
	);
}

function hello_activate()
{
}

function hello_deactivate()
{
}

function hello_world($page)
{
	$page = str_replace("<div id=\"content\">", "<div id=\"content\"><p>Hello World!<br />This is a sample MyBB Plugin (which can be disabled!) that displays this message on all pages.</p>", $page);
	return $page;
}

function hello_world_postbit($post)
{
	$post['message'] = "<strong>Hello world!</strong><br /><br />{$post['message']}";
}
?>

You may, at first, realize that this is much more complex than the basic nutshell I posted above.
So let's break it down into pieces:

PHP Code:
1
2
3
4
5
6
7
8
9
10
<?php
/**
 * MyBB 1.2
 * Copyright © 2006 MyBB Group, All Rights Reserved
 *
 * Website: http://www.mybboard.net
 * License: http://www.mybboard.net/eula.html
 *
 * $Id: hello.php 2932 2007-03-10 05:48:55Z chris $
 */

This is just the start of the PHP file, and the rest is just a comment, saying that this file is part of MyBB.  This can be ignored as this doesn't serve our purposes much.

PHP Code:
// Disallow direct access to this file for security reasons
if(!defined("IN_MYBB"))
{
	die("Direct initialization of this file is not allowed.<br /><br />Please make sure IN_MYBB is defined.");
}

This piece of code is really optional, and the plugin will work fine without it.
The idea of the code is to stop a user directly accessing the file.
After reading PHP tutorials, most will explain to you about PHP files a user will access directly.  MyBB plugins, however, should only be include'd, and not accessed.
An example of directly accessing the file would be, a user going to http://example.com/forums/inc/plugins/hello.php
You do not have to worry too much on the details of how the code snippet works - you just need to know that the if statement will be true if a user access the file directly (and thus, the script will die).

PHP Code:
$plugins->add_hook("pre_output_page", "hello_world");
$plugins->add_hook("postbit", "hello_world_postbit");

Okay, so now we see examples of adding hooks.  Again, I won't go into details of how it works - just assume that the function $plugins->add_hook exists and works well.
As you can see, we add hooks by calling the $plugins->add_hook() function.  The function has two required arguments - the name of the hook, and the name of our handler to the hook.
A list of available hooks can be found at the MyBB Wiki.
Hooks allow us to inject our own code into certain places in MyBB's code.  In the above example, the first line of code, hooks into the hook named pre_output_page.  This hook is run just before output data is sent to the user.  So what does this mean?  Basically, this tells MyBB, before the output is sent to the user, MyBB should execute the function named hello_world (which is defined later in the file).
Similarly, the second line tells MyBB to run the function named hello_world_postbit whenever it processes the hook postbit.  The postbit hook is executed every time just before a post is generated for showthread.

PHP Code:
1
2
3
4
5
6
7
8
9
10
11
function hello_info()
{
	return array(
		"name"			=> "Hello World!",
		"description"	=> "A sample plugin that prints hello world and changes the content of each post to 'Hello world!'",
		"website"		=> "http://www.mybboard.net",
		"author"		=> "MyBB Group",
		"authorsite"	=> "http://www.mybboard.net",
		"version"		=> "1.0",
	);
}

This is just the required _info() function we talked about eariler.  You should be able to figure out what it does.

PHP Code:
1
2
3
4
5
6
7
function hello_activate()
{
}

function hello_deactivate()
{
}

These demonstrate the optional _activate() and _deactivate() functions.  In this example, the functions do nothing (and, in this case, you could actually completely omit them).

PHP Code:
function hello_world($page)
{
	$page = str_replace("<div id=\"content\">", "<div id=\"content\"><p>Hello World!<br />This is a sample MyBB Plugin (which can be disabled!) that displays this message on all pages.</p>", $page);
	return $page;
}

Remember the hooks we added?  This is the function definition for the pre_output_page hook we added eariler (in other words, this function is executed before the page output is sent to the user).
Note that the pre_output_page hook supplies an argument (most hooks don't supply an argument).  If you want to modify the argument, take it and return your modified version.
In the above case, the function calls str_replace(), which is a PHP function which replaces some text (see PHP manual for more details on this function).  After transforming the argument $page, the function simply returns it.

PHP Code:
function hello_world_postbit($post)
{
	$post['message'] = "<strong>Hello world!</strong><br /><br />{$post['message']}";
}
?>

This is similar to the above function - it handles a plugin hook routine (postbit).
Instead of returning $post however, we just directly change it.  This is because the $post argument is actually passed by reference.  How passing by reference or value works is beyond this tutorial, but just remember that if something is passed by reference, you do not have to return a value.



Well, that's it for now.  Hopefully, you understood most things in this guide.  If you did, you should be able to write up some basic plugins.
If you don't know SQL, it's also probably a good time to learn it now.


My Blog
01-31-2008 10:58 PM
Find all posts by this user

« Next Oldest | Next Newest »

Messages In This Thread
Quick tutorial on making MyBB plugins - ZiNgA BuRgA - 01-31-2008 10:58 PM

 Standard Tools
Forum Jump: