Hook System

1. Introduction

What is it?

The hook system allows applicaton and mod developers to hook into phpBB's or their own functions.

Pre-defined hookable phpBB3 functions

In phpBB3 there are four functions you are able to hook into with your custom functions:

phpbb_user_session_handler(); which is called within user::setup after the session and the user object is correctly initialized.
append_sid($url, $params = false, $is_amp = true, $session_id = false); which is called for building urls (appending the session id)
$template->display($handle, $include_once = true); which is called directly before outputting the (not-yet-compiled) template.
exit_handler(); which is called at the very end of phpBB3's execution.

There are also valid external constants you may want to use if you embed phpBB3 into your application:

PHPBB_MSG_HANDLER (overwrite message handler)
PHPBB_DB_NEW_LINK (overwrite new_link parameter for sql_connect)
PHPBB_ROOT_PATH   (overwrite $phpbb_root_path)
PHPBB_ADMIN_PATH  (overwrite $phpbb_admin_path)

2. Allow hooks in functions/methods

The following examples explain how phpBB3 utilize the in-build hook system. You will be more interested in registering your hooks, but showing you this may help you understand the system better along the way.

First of all, this is how a function need to be layed out if you want to allow it to be hookable...

function my_own_function($my_first_parameter, $my_second_parameter)
{
	global $phpbb_hook;

	if ($phpbb_hook->call_hook(__FUNCTION__, $my_first_parameter, $my_second_parameter))
	{
		if ($phpbb_hook->hook_return(__FUNCTION__))
		{
			return $phpbb_hook->hook_return_result(__FUNCTION__);
		}
	}

	[YOUR CODE HERE]
}

Above, the call_hook function should always be mapping your function call... in regard to the number of parameters passed.

This is how you could make a method being hookable...

class my_hookable_object
{
	function hook_me($my_first_parameter, $my_second_parameter)
	{
		global $phpbb_hook;

		if ($phpbb_hook->call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))
		{
			if ($phpbb_hook->hook_return(array(__CLASS__, __FUNCTION__)))
			{
				return $phpbb_hook->hook_return_result(array(__CLASS__, __FUNCTION__));
			}
		}

		[YOUR CODE HERE]
	}
}

The only difference about calling it is the way you define the first parameter. For a function it is only __FUNCTION__, for a method it is array(__CLASS__, __FUNCTION__). In PHP4 __CLASS__ is always returning the class in lowercase.

Now, in phpBB there are some pre-defined hooks available, but how do you make your own hookable function available (and therefore allowing others to hook into it)? For this, there is the add_hook() method:

// Adding your own hookable function:
$phpbb_hook->add_hook('my_own_function');

// Adding your own hookable method:
$phpbb_hook->add_hook(array('my_hookable_object', 'hook_me'));

You are also able to remove the possibility of hooking a function/method by calling $phpbb_hook->remove_hook() with the same parameters as add_hook().
This comes in handy if you want to force some hooks not to be called - at all.

3. Registering hooks

Registering hooks

Now to actually defining your functions which should be called. For this we take the append_sid() function as an example (this function is able to be hooked by default). We create two classes, one being static and a function:

class my_append_sid_class
{
	// Our functions
	function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)
	{
		// Get possible previous results
		$result = $hook->previous_hook_result('append_sid');

		return $result['result'] . '<br />And i was the second one.';
	}
}

// Yet another class :o
class my_second_append_sid_class
{
	function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)
	{
		// Get possible previous results
		$result = $hook->previous_hook_result('append_sid');

		echo $result['result'] . '<br />I was called as the third one.';
	}
}

// And a normal function
function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)
{
	// Get possible previous results
	$result = $hook->previous_hook_result('append_sid');

	return 'I was called as the first one';
}

// Initializing the second class
$my_second_append_sid_class = new my_second_append_sid_class();

Make sure you add the same parameters to your function as is defined for the hookable function with one exception: The first variable is always &$hook... this is the hook object itself you are able to operate on.

Now we register the hooks one by one with the $phpbb_hook->register() method:

// Now, we register our append_sid "replacements" in a stacked way...
// Registering the function (this is called first)
$phpbb_hook->register('append_sid', 'my_append_sid');

// Registering the first class
$phpbb_hook->register('append_sid', array('my_append_sid_class', 'my_append_sid'));
$phpbb_hook->register('append_sid', array(&$my_second_append_sid_class, 'my_append_sid'));

With this you are even able to make your own functions that are already hooked itself being hooked again...

// Registering hook, which will be called
$phpbb_hook->register('append_sid', 'my_own_append_sid');

// Add hook to our called hook function
$phpbb_hook->add_hook('my_own_append_sid');

// Register added hook
$phpbb_hook->register('my_own_append_sid', 'also_my_own_append_sid');

Special treatment/chains

The register method is able to take a third argument to specify a special 'chain' mode. The valid modes are first, last and standalone

$phpbb_hook->register('append_sid', 'my_own_append_sid', 'first') would make sure that the function is called in the beginning of the chain. It is possible that more than one function is called within the first block - here the FIFO principle is used.

$phpbb_hook->register('append_sid', 'my_own_append_sid', 'last') would make sure that the function is called at the very end of the chain. It is possible that more than one function is called within the last block - here the FIFO principle is used.

$phpbb_hook->register('append_sid', 'my_own_append_sid', 'standalone') makes sure only the defined function is called. All other functions are removed from the chain and no other functions are added to it later on. If two applications try to trigger the standalone mode a PHP notice will be printed and the second function being discarded.

Only allowing hooks for some objects

Because the hook system is not able to differate between initialized objects and only operate on the class, you need to solve this on the code level.

One possibility would be to use a property:

class my_hookable_object
{
	function blabla()
	{
	}
}

class my_hookable_object2 extends my_hookable_object
{
	var $call_hook = true;

	function hook_me($my_first_parameter, $my_second_parameter)
	{
		if ($this->call_hook)
		{
			global $phpbb_hook;

			if ($phpbb_hook->call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))
			{
				if ($phpbb_hook->hook_return(array(__CLASS__, __FUNCTION__)))
				{
					return $phpbb_hook->hook_return_result(array(__CLASS__, __FUNCTION__));
				}
			}
		}

		return 'not hooked';
	}
}

function hooking(&$hook, $first, $second)
{
	return 'hooked';
}

$first_object = new my_hookable_object2();
$second_object = new my_hookable_object2();

$phpbb_hook->add_hook(array('my_hookable_object2', 'hook_me'));

$phpbb_hook->register(array('my_hookable_object2', 'hook_me'), 'hooking');

// Do not call the hook for $first_object
$first_object->call_hook = false;

echo $first_object->hook_me('first', 'second') . '<br />';
echo $second_object->hook_me('first', 'second') . '<br />';

OUTPUT:

not hooked
hooked

A different possibility would be using a function variable (which could be left out on passing the function variables to the hook):

class my_hookable_object
{
	function blabla()
	{
	}
}

class my_hookable_object2 extends my_hookable_object
{
	function hook_me($my_first_parameter, $my_second_parameter, $hook_me = true)
	{
		if ($hook_me)
		{
			global $phpbb_hook;

			if ($phpbb_hook->call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))
			{
				if ($phpbb_hook->hook_return(array(__CLASS__, __FUNCTION__)))
				{
					return $phpbb_hook->hook_return_result(array(__CLASS__, __FUNCTION__));
				}
			}
		}

		return 'not hooked';
	}
}

function hooking(&$hook, $first, $second)
{
	return 'hooked';
}

$first_object = new my_hookable_object2();
$second_object = new my_hookable_object2();

$phpbb_hook->add_hook(array('my_hookable_object2', 'hook_me'));

$phpbb_hook->register(array('my_hookable_object2', 'hook_me'), 'hooking');

echo $first_object->hook_me('first', 'second', false) . '<br />';
echo $second_object->hook_me('first', 'second') . '<br />';

OUTPUT:

not hooked
hooked

4. Result returning

Generally, the distinction has to be made if a function returns the result obtained from the called function or continue the execution. Based on the needs of the application this may differ. Therefore, the function returns the results only if the called hook function is returning a result.

Case 1 - Returning the result

Imagine the following function supporting hooks:

function append_sid($url, $params = false, $is_amp = true, $session_id = false)
{
	global $_SID, $_EXTRA_URL, $phpbb_hook;

	// Developers using the hook function need to globalise the $_SID and $_EXTRA_URL on their own and also handle it appropiatly.
	// They could mimick most of what is within this function
	if ($phpbb_hook->call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))
	{
		if ($phpbb_hook->hook_return(__FUNCTION__))
		{
			return $phpbb_hook->hook_return_result(__FUNCTION__);
		}
	}

	[...]
}

Now, the following function is yours. Since you return a value, the append_sid() function itself is returning it as is:

// The function called
function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)
{
	// Get possible previous results
	$result = $hook->previous_hook_result('append_sid');

	return 'Since i return something the append_sid() function will return my result.';
}

To be able to get the results returned from functions higher in the change the previous_hook_result() method should always be used, it returns an array('result' => [your result]) construct.

Case 2 - Not Returning any result

Sometimes applications want to return nothing and therefore force the underlying function to continue it's execution:

function append_sid($url, $params = false, $is_amp = true, $session_id = false)
{
	global $_SID, $_EXTRA_URL, $phpbb_hook;

	// Developers using the hook function need to globalise the $_SID and $_EXTRA_URL on their own and also handle it appropiatly.
	// They could mimick most of what is within this function
	if ($phpbb_hook->call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))
	{
		if ($phpbb_hook->hook_return(__FUNCTION__))
		{
			return $phpbb_hook->hook_return_result(__FUNCTION__);
		}
	}

	[...]
}

// The function called
function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)
{
	// Get possible previous results
	$result = $hook->previous_hook_result('append_sid');

	[...]

	// I only rewrite some variables, but return nothing. Therefore, the append_sid() function will not return my (non)result.
}

Please Note: The decision to return or not return is solely made of the very last function call within the hook chain. An example:

// The function called
function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)
{
	// Get possible previous results
	$result = $hook->previous_hook_result('append_sid');

	// $result is not filled

	return 'FILLED';
}

// This function is registered too and gets executed after my_append_sid()
function my_own_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)
{
	$result = $hook->previous_hook_result('append_sid');

	// $result is actually filled with $result['result'] = 'FILLED'
	// But i return nothing, therefore append_sid() continues it's execution.
}

// The way both functions are registered.
$phpbb_hook->register('append_sid', 'my_append_sid');
$phpbb_hook->register('append_sid', 'my_own_append_sid');

5. Embedding your hook files/classes/methods

There are basically two methods you are able to choose from:

1) Add a file to includes/hooks/. The file need to be prefixed by hook_. This file is included within common.php, you are able to register your hooks, include other files or functions, etc. It is advised to only include other files if needed (within a function call for example).

Please be aware that you need to purge your cache within the ACP to make your newly placed file available to phpBB3.

2) The second method is meant for those wanting to wrap phpBB3 without placing a custom file to the hooks directory. This is mostly done by including phpBB's files within the application file. To be able to register your hooks you need to create a function within your application:

// My function which gets executed within the hooks constuctor
function phpbb_hook_register(&$hook)
{
	$hook->register('append_sid', 'my_append_sid');
}

[...]

You should get the idea. ;)

6. Copyright and disclaimer

This application is opensource software released under the GPL. Please see source code and the docs directory for more details. This package and its contents are Copyright (c) 2000, 2002, 2005, 2007 phpBB Group, All Rights Reserved.