I think i have a basic to moderately good understand of php, but i can just not understand how to actually implement hooks correctly.
For example, if i say wanted to make a plugin with did something like count the number of total thread views and then display them on the index in the stats, would i need a hook?
My initial thinking would be:
$plugins->add_hook("stats_start", "my_function_here");
?
regardless if that is correct or not, how does my function interact with the hook i've taken? For example (taken from hello_world):
$plugins->add_hook("pre_output_page", "hello_world");
is used, where the function hello_world is:
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;
}
In this case, is pre_output_page just basically running the function hello world just before the page is loaded?
If someone could provide other example -> explanation pairs that would be brilliant.
pretty simple actually.
first, find where the hooks are in the code you want to interact with, and see if hey are passing any variables with them. if they are passing variables, you need to include that variable name (or suitable substitute) in your function declaration. you also need to see if the data you need or want to use are already available, if so, you need to "global" those so you can access them.
example: in /inc/functions_post.php there is the build_postbit() function. In that function is $plugins->run_hooks('postbit', $post);
This is passing the $post variable as part of the hook, so you need to account for it in your plugin:
$plugins->add_hook('postbit', 'my_function');
function my_function(&$post);
{
//do stuff
}
if you want to use a variable other than post, say some fictitious variable $foo that is part of the build_postbit() function then you do
$plugins->add_hook('postbit', 'my_function');
function my_function(&$post);
{
global $foo;
//do stuff with $foo
}
if you want to use your own variable and update over all the times the postbit hook is called then you can use $bar to store that
$plugins->add_hook('postbit', 'my_function');
function my_function(&$post);
{
global $foo, $bar;
//do stuff with $foo
//do stuff with $bar like
$bar++;
}
and since $bar is global, it will increment each time the postbit hook is called on that page, thus you will know that $bar posts have been made on that page, and at any time when postbit hook is called you will know what post you are at
btw, your specific example of counting the total number of thread views is already part of the core features and tracked in the threads table, so if you have a better example of what you are wanting to do, we can help you with specifics.
I'm not sure if i fundamentally don't understand the logic behind this or what; even after going through your post. If you took as an example:
$plugins->run_hooks('postbit', my_function);
function my_function(&$post)...
Firstly, what does the fact that postbit and my_function in the same line actually do, will it run my_function in the postbit? You said it is passing the variable, but in real terms what is it doing, in example terms. (e.g. Is it putting a red bus in the postbit...)
Everyone says the hook system is intuitive, but how do i know what i need and where.
Even with that relationship above between postbit, my_function and post, how are they interacting?
when you create a plugin, you have lines like
$plugin->add_hook("postbit", "my_function_name");
since mybb loads all the active plugin files with each page load, it builds a list of plugin hook names and all of the functions the plugin authors associate with each hook. In the above, the "my_function_name" function is associated with the "postbit" hook.
in the example here, "postbit" is the name of the hook and when mybb runs across $plugins->run_hook("postbit", $post); in the core code, it looks up the list of hooks and functions it built at page load and then calls those functions to be run, one at time, passing the variable $post to the "my_function_name" in the plugin file to it to do something.
when "my_function_name" is done, MyBB will call the next plugin function that is linked or associated with the "postbit" hook.
this is also why it is not a good idea to have simple plugins that do just template edits or things a basic core edit can do. MyBB has to load each plugin file into memory and any hooks with every page load, so its a waste of resources if the plugin is not really doing anything.
On a note, you do
not have to match variable names. For the postbit you could have your function look like this (totally contrived example):
function pluginname_postbit_func(&$pb)
{
$pb['count']++;
}
And it will work. In the MyBB core files the variable is called $postbit, in your plugin you call it $pb, but both point at the same region of memory (in my example, because we're receiving by reference) and so it works. Its two names for the same thing basically. I'm just making this point, because some other authors have done this, and if you look at their code I don't want you any more confused than you are
in standard distribution zip file there is already two plugins included. akismet.php and hello.php.
try to understand how do hello.php works. it's simple plugin and is provided as example.
akismet.php relatively complex plugin, so I suggest to download some plugins from
http://mods.mybb.com/ and learn how do they work. better to start with plugins which are popular and provide solutions in the same area of interest.
a very good idea will be to have separate test environment to develop and test your plugin. that will save you from lot of pain