8 files changed, 1201 insertions, 10 deletions
diff --git a/phpBB/common.php b/phpBB/common.php
index 1be8eeec9b..2d8a654dac 100644
--- a/phpBB/common.php
+++ b/phpBB/common.php
@@ -190,4 +190,13 @@ unset($dbpasswd);
 // Grab global variables, re-cache if necessary
 $config = $cache->obtain_config();
 
+// Add own hook handler
+require($phpbb_root_path . 'includes/hooks/index.' . $phpEx);
+$phpbb_hook = new phpbb_hook(array('exit_handler', 'phpbb_user_session_handler', 'append_sid', array('template', 'display')));
+
+foreach ($cache->obtain_hooks() as $hook)
+{
+	include($phpbb_root_path . 'includes/hooks/' . $hook . '.' . $phpEx);
+}
+
 ?>
 \ No newline at end of file
diff --git a/phpBB/docs/CHANGELOG.html b/phpBB/docs/CHANGELOG.html
index 5556adfc4f..bea00592bc 100644
--- a/phpBB/docs/CHANGELOG.html
+++ b/phpBB/docs/CHANGELOG.html
@@ -107,6 +107,7 @@
 		<li>[Fix] Always display the quote button as the most accessible one - edit is always before quote (Bug #14403)</li>
 		<li>[Fix] Use correct dimension (width x height) in ACP (Bug #14452)</li>
 		<li>[Fix] Only display PM history links if there are PM's to be displayed (Bug #14484)</li>
+		<li>[Feature] Added completely new hook system to allow better application/mod integration - see docs/hook_system.html</li>
 	</ul>
 
 	<a name="v30rc4"></a><h3>1.ii. Changes since 3.0.RC4</h3>
diff --git a/phpBB/docs/hook_system.html b/phpBB/docs/hook_system.html
new file mode 100644
index 0000000000..d877757050
--- /dev/null
+++ b/phpBB/docs/hook_system.html
@@ -0,0 +1,858 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en" xml:lang="en">
+<head>
+
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<meta http-equiv="content-style-type" content="text/css" />
+<meta http-equiv="content-language" content="en" />
+<meta http-equiv="imagetoolbar" content="no" />
+<meta name="resource-type" content="document" />
+<meta name="distribution" content="global" />
+<meta name="copyright" content="2007 phpBB Group" />
+<meta name="keywords" content="" />
+<meta name="description" content="Hook System explanation" />
+<title>phpBB3 &bull; Hook System</title>
+
+<style type="text/css">
+<!--
+
+/*
+	The original "prosilver" theme for phpBB3
+	Created by subBlue design :: http://www.subBlue.com
+*/
+
+* { margin: 0; padding: 0; }
+
+html { font-size: 100%; height: 100%; margin-bottom: 1px; }
+
+body {
+	font-family: Verdana, Helvetica, Arial, sans-serif;
+	color: #828282;
+	background-color: #FFFFFF;
+	font-size: 12px;
+	margin: 0;
+	padding: 12px 0;
+}
+
+img { border-width: 0; }
+
+p {
+	line-height: 1.3em;
+	font-size: 1.1em;
+	margin-bottom: 1.5em;
+}
+
+hr {
+	border: 0 none #FFFFFF;
+	border-top: 1px solid #CCCCCC;
+	height: 1px;
+	margin: 5px 0;
+	display: block;
+	clear: both;
+}
+
+html, body {
+	color: #536482;
+	background-color: #FFFFFF;
+}
+
+#doc-description h1 {
+	font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
+	margin-right: 200px;
+	color: #FFFFFF;
+	margin-top: 15px;
+	font-weight: bold;
+	font-size: 2em;
+	color: #fff;
+}
+
+h1 {
+	font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
+	font-weight: normal;
+	color: #000;
+	font-size: 2em;
+	margin: 0.8em 0 0.2em 0;
+}
+
+h2 {
+	font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
+	font-weight: normal;
+	color: #28313F;
+	font-size: 1.5em;
+	margin: 0.8em 0 0.2em 0;
+}
+
+h3 {
+	font-family: Arial, Helvetica, sans-serif;
+	font-weight: bold;
+	border-bottom: 1px solid #CCCCCC;
+	margin-bottom: 3px;
+	padding-bottom: 2px;
+	font-size: 1.05em;
+	color: #115098;
+	margin-top: 20px;
+}
+
+.good { color: green; }
+.bad { color: red; }
+
+.version {
+	margin-top: 20px;
+	text-align: left;
+	font-size: 70%;
+	color: #006600;
+	border-top: 1px solid #ccc;
+}
+
+code { 
+	color: #006600; 
+	font-weight: normal; 
+	font-family: 'Courier New', monospace; 
+	border-color: #D1D7DC; 
+	border-width: 1px; 
+	border-style: solid; 
+	background-color: #FAFAFA; 
+}
+
+#wrap {
+	padding: 0 20px;
+	min-width: 650px;
+}
+
+#simple-wrap {
+	padding: 6px 10px;
+}
+
+#page-body {
+	margin: 4px 0;
+	clear: both;
+}
+
+#page-footer {
+	clear: both;
+}
+
+#logo {
+	float: left;
+	width: auto;
+	padding: 10px 13px 0 10px;
+}
+
+a#logo:hover {
+	text-decoration: none;
+}
+
+#doc-description {
+	float: left;
+	width: 70%;
+}
+
+#doc-description h1 {
+	margin-right: 0;
+}
+
+.headerbar {
+	background: #ebebeb none repeat-x 0 0;
+	color: #FFFFFF;
+	margin-bottom: 4px;
+	padding: 0 5px;
+}
+
+span.corners-top, span.corners-bottom, span.corners-top span, span.corners-bottom span {
+	font-size: 1px;
+	line-height: 1px;
+	display: block;
+	height: 5px;
+	background-repeat: no-repeat;
+}
+
+span.corners-top {
+	background-image: none;
+	background-position: 0 0;
+	margin: 0 -5px;
+}
+
+span.corners-top span {
+	background-image: none;
+	background-position: 100% 0;
+}
+
+span.corners-bottom {
+	background-image: none;
+	background-position: 0 100%;
+	margin: 0 -5px;
+	clear: both;
+}
+
+span.corners-bottom span {
+	background-image: none;
+	background-position: 100% 100%;
+}
+
+.paragraph {
+	padding: 0 10px;
+	margin-bottom: 4px;
+	background-repeat: no-repeat;
+	background-position: 100% 0;
+	background-color: #ECF3F7;
+}
+
+.paragraph:target .content {
+	color: #000000;
+}
+
+.paragraph:target h3 a {
+	color: #000000;
+}
+
+.content {
+	color: #333333;
+}
+
+.content h2, .panel h2 {
+	color: #115098;
+	border-bottom-color:  #CCCCCC;
+}
+
+a:link	{ color: #898989; text-decoration: none; }
+a:visited	{ color: #898989; text-decoration: none; }
+a:hover	{ color: #d3d3d3; text-decoration: underline; }
+a:active	{ color: #d2d2d2; text-decoration: none; }
+
+hr {
+	border-color: #FFFFFF;
+	border-top-color: #CCCCCC;
+}
+
+.menu {
+	background-color: #cadceb;
+}
+
+.headerbar {
+	background-color: #12A3EB;
+	background-image: url("bg_header.gif");
+	color: #FFFFFF;
+}
+
+.panel {
+	background-color: #ECF1F3;
+	color: #28313F;
+}
+
+
+span.corners-top {
+	background-image: url("corners_left.png");
+}
+
+span.corners-top span {
+	background-image: url("corners_right.png");
+}
+
+span.corners-bottom {
+	background-image: url("corners_left.png");
+}
+
+span.corners-bottom span {
+	background-image: url("corners_right.png");
+}
+
+.error {
+	color: #BC2A4D;
+}
+
+a:link	{ color: #105289; }
+a:visited	{ color: #105289; }
+a:hover	{ color: #D31141; }
+a:active	{ color: #368AD2; }
+
+.paragraph span.corners-top, .paragraph span.corners-bottom {
+	margin: 0 -10px;
+}
+
+.content {
+	padding: 0;
+	line-height: 1.48em;
+	color: #333333;
+}
+
+.content h2, .panel h2 {
+	color: #115098;
+	border-bottom-color:  #CCCCCC;
+}
+
+.notice {
+	border-top-color:  #CCCCCC;
+}
+
+.codebox {
+	padding: 3px;
+	background-color: #FFFFFF;
+	border: 1px solid #C9D2D8;
+	font-size: 1em;
+	margin-bottom: 10px;
+	display: block;
+	font: 0.9em Monaco, "Andale Mono","Courier New", Courier, mono;
+	line-height: 1.3em;
+}
+
+* html hr { margin: 0; }
+* html span.corners-top, * html span.corners-bottom { background-image: url("corners_left.gif"); }
+* html span.corners-top span, * html span.corners-bottom span { background-image: url("corners_right.gif"); }
+
+.back2top {
+	clear: both;
+	height: 11px;
+	text-align: right;
+}
+
+.content ol {
+	margin-left: 25px;
+}
+
+//-->
+</style>
+
+</head>
+
+<body id="phpbb" class="section-docs">
+
+<div id="wrap">
+	<a id="top" name="top" accesskey="t"></a>
+	<div id="page-header">
+		<div class="headerbar">
+			<div class="inner"><span class="corners-top"><span></span></span>
+
+			<div id="doc-description">
+				<a href="../index.php" id="logo"><img src="site_logo.gif" alt="" /></a>
+				<h1>Hook System</h1>
+				<p>This is an explanation of how to use the phpBB3 hook system.</p>
+				<p style="display: none;"><a href="#start_here">Skip</a></p>
+			</div>
+
+			<span class="corners-bottom"><span></span></span></div>
+		</div>
+	</div>
+
+	<a name="start_here"></a>
+
+	<div id="page-body">
+
+	<h1>Hook System</h1>
+
+	<div class="paragraph menu">
+		<div class="inner"><span class="corners-top"><span></span></span>
+
+		<div class="content">
+
+			<ol>
+				<li><a href="#intro">Introduction</a></li>
+				<li><a href="#use">Allow hooks in functions/methods</a></li>
+				<li><a href="#register">Registering hooks</a></li>
+				<li><a href="#return">Result returning</a></li>
+				<li><a href="#embed">Embedding your hook files/classes/methods</a></li>
+				<li><a href="#disclaimer">Copyright and disclaimer</a></li>
+			</ol>
+
+		</div>
+
+		<span class="corners-bottom"><span></span></span></div>
+	</div>
+
+	<hr />
+
+	<a name="intro"></a><h2>1. Introduction</h2>
+
+	<div class="paragraph">
+		<div class="inner"><span class="corners-top"><span></span></span>
+
+		<div class="content">
+
+<h3>What is it?</h3>
+
+<p>The hook system allows applicaton and mod developers to hook into phpBB's or their own functions.</p>
+
+<h3>Pre-defined hookable phpBB3 functions</h3>
+
+<p>In phpBB3 there are four functions you are able to hook into with your custom functions:</p>
+
+<p><code>phpbb_user_session_handler();</code> which is called within user::setup after the session and the user object is correctly initialized.<br />
+<code>append_sid($url, $params = false, $is_amp = true, $session_id = false);</code> which is called for building urls (appending the session id)<br />
+<code>$template-&gt;display($handle, $include_once = true);</code> which is called directly before outputting the (not-yet-compiled) template.<br />
+<code>exit_handler();</code> which is called at the very end of phpBB3's execution.</p>
+
+<p>There are also valid external constants you may want to use if you embed phpBB3 into your application:</p>
+
+<div class="codebox"><pre>
+PHPBB_MSG_HANDLER (overwrite message handler)
+PHPBB_ROOT_PATH   (overwrite $phpbb_root_path)
+PHPBB_ADMIN_PATH  (overwrite $phpbb_admin_path)
+</pre></div>
+
+		</div>
+
+		<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
+
+		<span class="corners-bottom"><span></span></span></div>
+	</div>
+
+	<a name="use"></a><h2>2. Allow hooks in functions/methods</h2>
+
+	<div class="paragraph">
+		<div class="inner"><span class="corners-top"><span></span></span>
+
+		<div class="content">
+
+<p>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.</p>
+
+<p>First of all, this is how a function need to be layed out if you want to allow it to be hookable...</p>
+
+<div class="codebox"><pre>
+function my_own_function($my_first_parameter, $my_second_parameter)
+{
+	global $phpbb_hook;
+
+	if ($phpbb_hook-&gt;call_hook(__FUNCTION__, $my_first_parameter, $my_second_parameter))
+	{
+		if ($phpbb_hook-&gt;hook_return(__FUNCTION__))
+		{
+			return $phpbb_hook-&gt;hook_return_result(__FUNCTION__);
+		}
+	}
+
+	[YOUR CODE HERE]
+}
+</pre></div>
+
+<p>Above, the call_hook function should always be mapping your function call... in regard to the number of parameters passed.</p>
+
+<p>This is how you could make a method being hookable...</p>
+
+<div class="codebox"><pre>
+class my_hookable_object
+{
+	function hook_me($my_first_parameter, $my_second_parameter)
+	{
+		global $phpbb_hook;
+
+		if ($phpbb_hook-&gt;call_hook(array(get_class(), __FUNCTION__), $my_first_parameter, $my_second_parameter))
+		{
+			if ($phpbb_hook-&gt;hook_return(array(get_class(), __FUNCTION__)))
+			{
+				return $phpbb_hook-&gt;hook_return_result(array(get_class(), __FUNCTION__));
+			}
+		}
+
+		[YOUR CODE HERE]
+	}
+}
+</pre></div>
+
+<p>The only difference about calling it is the way you define the first parameter. For a function it is only <code>__FUNCTION__</code>, for a method it is <code>array(get_class(), __FUNCTION__)</code>.</p>
+
+<p>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:</p>
+
+<div class="codebox"><pre>
+// Adding your own hookable function:
+$phpbb_hook-&gt;add_hook('my_own_function');
+
+// Adding your own hookable method:
+$phpbb_hook-&gt;add_hook(array('my_hookable_object', 'hook_me'));
+</pre></div>
+
+<p>You are also able to remove the possibility of hooking a function/method by calling <code>$phpbb_hook-&gt;remove_hook()</code> with the same parameters as add_hook().<br />
+This comes in handy if you want to force some hooks not to be called - at all.</p>
+
+		</div>
+
+		<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
+
+		<span class="corners-bottom"><span></span></span></div>
+	</div>
+
+	<a name="register"></a><h2>3. Registering hooks</h2>
+
+	<div class="paragraph">
+		<div class="inner"><span class="corners-top"><span></span></span>
+
+		<div class="content">
+
+		<h3>Registering hooks</h3>
+
+<p>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:</p>
+
+<div class="codebox"><pre>
+class my_append_sid_class
+{
+	// Our functions
+	function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
+	{
+		// Get possible previous results
+		$result = $hook-&gt;previous_hook_result('append_sid');
+
+		return $result['result'] . '&lt;br /&gt;And i was the second one.';
+	}
+}
+
+// Yet another class :o
+class my_second_append_sid_class
+{
+	function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
+	{
+		// Get possible previous results
+		$result = $hook-&gt;previous_hook_result('append_sid');
+
+		echo $result['result'] . '&lt;br /&gt;I was called as the third one.';
+	}
+}
+
+// And a normal function
+function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
+{
+	// Get possible previous results
+	$result = $hook-&gt;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();
+</pre></div>
+
+<p>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 <code>&amp;$hook</code>... this is the hook object itself you are able to operate on.</p>
+
+<p>Now we register the hooks one by one with the <code>$phpbb_hook-&gt;register()</code> method:</p>
+
+<div class="codebox"><pre>
+// Now, we register our append_sid &quot;replacements&quot; in a stacked way...
+// Registering the function (this is called first)
+$phpbb_hook-&gt;register('append_sid', 'my_append_sid');
+
+// Registering the first class
+$phpbb_hook-&gt;register('append_sid', array('my_append_sid_class', 'my_append_sid'));
+$phpbb_hook-&gt;register('append_sid', array(&amp;$my_second_append_sid_class, 'my_append_sid'));
+</pre></div>
+
+<p>With this you are even able to make your own functions that are already hooked itself being hooked again...</p>
+
+<div class="codebox"><pre>
+// Registering hook, which will be called
+$phpbb_hook-&gt;register('append_sid', 'my_own_append_sid');
+
+// Add hook to our called hook function
+$phpbb_hook-&gt;add_hook('my_own_append_sid');
+
+// Register added hook
+$phpbb_hook-&gt;register('my_own_append_sid', 'also_my_own_append_sid');
+</pre></div>
+
+		<h3>Special treatment/chains</h3>
+
+		<p>The <code>register</code> method is able to take a third argument to specify a special 'chain' mode. The valid modes are <code>first</code>, <code>last</code> and <code>standalone</code></p>
+
+		<p><code>$phpbb_hook-&gt;register('append_sid', 'my_own_append_sid', 'first')</code> 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.</p>
+
+		<p><code>$phpbb_hook-&gt;register('append_sid', 'my_own_append_sid', 'last')</code> 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.</p>
+
+		<p><code>$phpbb_hook-&gt;register('append_sid', 'my_own_append_sid', 'standalone')</code> 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.</p>
+
+		<h3>Only allowing hooks for some objects</h3>
+
+		<p>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.</p>
+
+		<p>One possibility would be to use a property:</p>
+
+		<div class="codebox"><pre>
+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-&gt;call_hook)
+		{
+			global $phpbb_hook;
+
+			if ($phpbb_hook-&gt;call_hook(array(get_class(), __FUNCTION__), $my_first_parameter, $my_second_parameter))
+			{
+				if ($phpbb_hook-&gt;hook_return(array(get_class(), __FUNCTION__)))
+				{
+					return $phpbb_hook-&gt;hook_return_result(array(get_class(), __FUNCTION__));
+				}
+			}
+		}
+
+		return 'not hooked';
+	}
+}
+
+function hooking(&amp;$hook, $first, $second)
+{
+	return 'hooked';
+}
+
+$first_object = new my_hookable_object2();
+$second_object = new my_hookable_object2();
+
+$phpbb_hook-&gt;add_hook(array('my_hookable_object2', 'hook_me'));
+
+$phpbb_hook-&gt;register(array('my_hookable_object2', 'hook_me'), 'hooking');
+
+// Do not call the hook for $first_object
+$first_object-&gt;call_hook = false;
+
+echo $first_object-&gt;hook_me('first', 'second') . '&lt;br /&gt;';
+echo $second_object-&gt;hook_me('first', 'second') . '&lt;br /&gt;';
+</pre></div>
+
+<p>OUTPUT:</p>
+
+<div class="codebox"><pre>
+not hooked
+hooked 
+</pre></div>
+
+		<p>A different possibility would be using a function variable (which could be left out on passing the function variables to the hook):</p>
+
+		<div class="codebox"><pre>
+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-&gt;call_hook(array(get_class(), __FUNCTION__), $my_first_parameter, $my_second_parameter))
+			{
+				if ($phpbb_hook-&gt;hook_return(array(get_class(), __FUNCTION__)))
+				{
+					return $phpbb_hook-&gt;hook_return_result(array(get_class(), __FUNCTION__));
+				}
+			}
+		}
+
+		return 'not hooked';
+	}
+}
+
+function hooking(&amp;$hook, $first, $second)
+{
+	return 'hooked';
+}
+
+$first_object = new my_hookable_object2();
+$second_object = new my_hookable_object2();
+
+$phpbb_hook-&gt;add_hook(array('my_hookable_object2', 'hook_me'));
+
+$phpbb_hook-&gt;register(array('my_hookable_object2', 'hook_me'), 'hooking');
+
+echo $first_object-&gt;hook_me('first', 'second', false) . '&lt;br /&gt;';
+echo $second_object-&gt;hook_me('first', 'second') . '&lt;br /&gt;';
+		</pre></div>
+
+		<p>OUTPUT:</p>
+
+		<div class="codebox"><pre>
+not hooked
+hooked 
+		</pre></div>
+
+		</div>
+
+		<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
+
+		<span class="corners-bottom"><span></span></span></div>
+	</div>
+
+	<a name="return"></a><h2>4. Result returning</h2>
+
+	<div class="paragraph">
+		<div class="inner"><span class="corners-top"><span></span></span>
+
+		<div class="content">
+
+<p>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.</p>
+
+<h3>Case 1 - Returning the result</h3>
+
+<p>Imagine the following function supporting hooks:</p>
+
+<div class="codebox"><pre>
+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-&gt;call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))
+	{
+		if ($phpbb_hook-&gt;hook_return(__FUNCTION__))
+		{
+			return $phpbb_hook-&gt;hook_return_result(__FUNCTION__);
+		}
+	}
+
+	[...]
+}
+</pre></div>
+
+<p>Now, the following function is yours. Since you return a value, the append_sid() function itself is returning it as is:</p>
+
+<div class="codebox"><pre>
+// The function called
+function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
+{
+	// Get possible previous results
+	$result = $hook-&gt;previous_hook_result('append_sid');
+
+	return 'Since i return something the append_sid() function will return my result.';
+}
+</pre></div>
+
+<p>To be able to get the results returned from functions higher in the change the <code>previous_hook_result()</code> method should always be used, it returns an <code>array('result' => [your result])</code> construct.</p>
+
+<h3>Case 2 - Not Returning any result</h3>
+
+<p>Sometimes applications want to return nothing and therefore force the underlying function to continue it's execution:</p>
+
+<div class="codebox"><pre>
+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-&gt;call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))
+	{
+		if ($phpbb_hook-&gt;hook_return(__FUNCTION__))
+		{
+			return $phpbb_hook-&gt;hook_return_result(__FUNCTION__);
+		}
+	}
+
+	[...]
+}
+
+// The function called
+function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
+{
+	// Get possible previous results
+	$result = $hook-&gt;previous_hook_result('append_sid');
+
+	[...]
+
+	// I only rewrite some variables, but return nothing. Therefore, the append_sid() function will not return my (non)result.
+}
+</pre></div>
+
+<p>Please Note: The decision to return or not return is solely made of the very last function call within the hook chain. An example:</p>
+
+<div class="codebox"><pre>
+// The function called
+function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
+{
+	// Get possible previous results
+	$result = $hook-&gt;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(&amp;$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');
+</pre></div>
+
+		</div>
+
+		<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
+
+		<span class="corners-bottom"><span></span></span></div>
+	</div>
+
+	<a name="embed"></a><h2>5. Embedding your hook files/classes/methods</h2>
+
+	<div class="paragraph">
+		<div class="inner"><span class="corners-top"><span></span></span>
+
+		<div class="content">
+
+<p>There are basically two methods you are able to choose from:</p>
+
+<p>1) Add a file to includes/hooks/. The file need to be prefixed by <code>hook_</code>. 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).</p>
+
+<p>Please be aware that you need to purge your cache within the ACP to make your newly placed file available to phpBB3.</p>
+
+<p>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:</p>
+
+<div class="codebox"><pre>
+// My function which gets executed within the hooks constuctor
+function phpbb_hook_register(&amp;$hook)
+{
+	$hook-&gt;register('append_sid', 'my_append_sid');
+}
+
+[...]
+</pre></div>
+
+<p>You should get the idea. ;)</p>
+
+		</div>
+
+		<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
+
+		<span class="corners-bottom"><span></span></span></div>
+	</div>
+
+	<a name="disclaimer"></a><h2>6. Copyright and disclaimer</h2>
+
+	<div class="paragraph">
+		<div class="inner"><span class="corners-top"><span></span></span>
+
+		<div class="content">
+
+	<p>This application is opensource software released under the <a href="http://opensource.org/licenses/gpl-license.php">GPL</a>. Please see source code and the docs directory for more details. This package and its contents are Copyright (c) 2000, 2002, 2005, 2007 <a href="http://www.phpbb.com/">phpBB Group</a>, All Rights Reserved.</p>
+
+		</div>
+
+		<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
+
+		<span class="corners-bottom"><span></span></span></div>
+	</div>
+
+	<div id="page-footer">
+		<div class="version">$Id$</div>
+	</div>
+</div></div>
+
+<div>
+	<a id="bottom" name="bottom" accesskey="z"></a>
+</div>
+
+</body>
+</html>
diff --git a/phpBB/includes/cache.php b/phpBB/includes/cache.php
index 97b98e1227..77fc5e30f3 100644
--- a/phpBB/includes/cache.php
+++ b/phpBB/includes/cache.php
@@ -403,6 +403,38 @@ class cache extends acm
 
 		return $usernames;
 	}
+
+	/**
+	* Obtain hooks...
+	*/
+	function obtain_hooks()
+	{
+		global $phpbb_root_path, $phpEx;
+
+		if (($hook_files = $this->get('_hooks')) === false)
+		{
+			$hook_files = array();
+
+			// Now search in acp and mods folder for permissions_ files.
+			$dh = @opendir($phpbb_root_path . 'includes/hooks/');
+
+			if ($dh)
+			{
+				while (($file = readdir($dh)) !== false)
+				{
+					if (strpos($file, 'hook_') === 0 && substr($file, -(strlen($phpEx) + 1)) === '.' . $phpEx)
+					{
+						$hook_files[] = substr($file, 0, -(strlen($phpEx) + 1));
+					}
+				}
+				closedir($dh);
+			}
+
+			$this->put('_hooks', $hook_files);
+		}
+
+		return $hook_files;
+	}
 }
 
 ?>
 \ No newline at end of file
diff --git a/phpBB/includes/functions.php b/phpBB/includes/functions.php
index 004c4d8828..60d4297ff4 100644
--- a/phpBB/includes/functions.php
+++ b/phpBB/includes/functions.php
@@ -1564,7 +1564,8 @@ function on_page($num_items, $per_page, $start)
 // Server functions (building urls, redirecting...)
 
 /**
-* Append session id to url
+* Append session id to url.
+* This function supports hooks.
 *
 * @param string $url The url the session id needs to be appended to (can have params)
 * @param mixed $params String or array of additional url parameters
@@ -1579,17 +1580,19 @@ function on_page($num_items, $per_page, $start)
 * append_sid("{$phpbb_root_path}viewtopic.$phpEx", array('t' => 1, 'f' => 2));
 * </code>
 *
-* Ability to use own function <code>append_sid_phpbb_hook</code> as a hook. It is called in favor of this function.
 */
 function append_sid($url, $params = false, $is_amp = true, $session_id = false)
 {
-	global $_SID, $_EXTRA_URL;
+	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 (function_exists('append_sid_phpbb_hook'))
+	if ($phpbb_hook->call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))
 	{
-		return append_sid_phpbb_hook($url, $params, $is_amp, $session_id);
+		if ($phpbb_hook->hook_return(__FUNCTION__))
+		{
+			return $phpbb_hook->hook_return_result(__FUNCTION__);
+		}
 	}
 
 	// Assign sid if session id is not specified
@@ -4333,21 +4336,46 @@ function garbage_collection()
 }
 
 /**
-* Handler for exit calls in phpBB
+* Handler for exit calls in phpBB.
+* This function supports hooks.
 *
-* Ability to use own function <code>exit_handler_phpbb_hook</code> as a hook. It is called in favor of this function.
+* Note: This function is called after the template has been outputted.
 */
 function exit_handler()
 {
-	if (function_exists('exit_handler_phpbb_hook'))
+	global $phpbb_hook;
+
+	if ($phpbb_hook->call_hook(__FUNCTION__))
 	{
-		return exit_handler_phpbb_hook();
+		if ($phpbb_hook->hook_return(__FUNCTION__))
+		{
+			return $phpbb_hook->hook_return_result(__FUNCTION__);
+		}
 	}
 
 	exit;
 }
 
 /**
+* Handler for init calls in phpBB. This function is called in user::setup();
+* This function supports hooks.
+*/
+function phpbb_user_session_handler()
+{
+	global $phpbb_hook;
+
+	if ($phpbb_hook->call_hook(__FUNCTION__))
+	{
+		if ($phpbb_hook->hook_return(__FUNCTION__))
+		{
+			return $phpbb_hook->hook_return_result(__FUNCTION__);
+		}
+	}
+
+	return;
+}
+
+/**
 * @package phpBB3
 */
 class bitfield
diff --git a/phpBB/includes/hooks/index.php b/phpBB/includes/hooks/index.php
new file mode 100644
index 0000000000..e784b460a9
--- /dev/null
+++ b/phpBB/includes/hooks/index.php
@@ -0,0 +1,250 @@
+<?php
+/** 
+*
+* @package phpBB3
+* @version $Id$
+* @copyright (c) 2007 phpBB Group 
+* @license http://opensource.org/licenses/gpl-license.php GNU Public License 
+*
+*/
+
+/**
+* @ignore
+*/
+if (!defined('IN_PHPBB'))
+{
+	exit;
+}
+
+/**
+* phpBB Hook Class
+* @package phpBB3
+*/
+class phpbb_hook
+{
+	/**
+	* Registered hooks
+	*/
+	var $hooks = array();
+
+	/**
+	* Results returned by functions called
+	*/
+	var $hook_result = array();
+
+	/**
+	* internal pointer
+	*/
+	var $current_hook = NULL;
+
+	/**
+	* Initialize hook class.
+	*
+	* @param array $valid_hooks array containing the hookable functions/methods
+	*/
+	function phpbb_hook($valid_hooks)
+	{
+		foreach ($valid_hooks as $_null => $method)
+		{
+			$this->add_hook($method);
+		}
+
+		if (function_exists('phpbb_hook_register'))
+		{
+			phpbb_hook_register($this);
+		}
+	}
+
+	/**
+	* Register function/method to be called within hook
+	* This function is normally called by the modification/application to attach/register the functions.
+	*
+	* @param mixed $definition Declaring function (with __FUNCTION__) or class with array(get_class(), __FUNCTION)
+	* @param mixed $hook The replacement function/method to be called. Passing function name or array with object/class definition
+	* @param string $mode Specify the priority/chain mode. 'normal' -> hook gets appended to the chain. 'standalone' -> only the specified hook gets called - later hooks are not able to overwrite this (E_NOTICE is triggered then). 'first' -> hook is called as the first one within the chain. 'last' -> hook is called as the last one within the chain.
+	*/
+	function register($definition, $hook, $mode = 'normal')
+	{
+		$class = (!is_array($definition)) ? '__global' : $definition[0];
+		$function = (!is_array($definition)) ? $definition : $definition[1];
+
+		// Method able to be hooked?
+		if (isset($this->hooks[$class][$function]))
+		{
+			switch ($mode)
+			{
+				case 'standalone':
+					if (!isset($this->hooks[$class][$function]['standalone']))
+					{
+						$this->hooks[$class][$function] = array('standalone' => $hook);
+					}
+					else
+					{
+						trigger_error('Hook not able to be called standalone, previous hook already standalone.', E_NOTICE);
+					}
+				break;
+
+				case 'first':
+				case 'last':
+					$this->hooks[$class][$function][$mode][] = $hook;
+				break;
+
+				case 'normal':
+				default:
+					$this->hooks[$class][$function]['normal'][] = $hook;
+				break;
+			}
+		}
+	}
+
+	/**
+	* Calling all functions/methods attached to a specified hook.
+	* Called by the function allowing hooks...
+	*
+	* @param mixed $definition Declaring function (with __FUNCTION__) or class definition with array(). Must be call_user_func_array() compatible.
+	* @return bool False if no hook got executed, true otherwise
+	*/
+	function call_hook($definition)
+	{
+		$class = (!is_array($definition)) ? '__global' : $definition[0];
+		$function = (!is_array($definition)) ? $definition : $definition[1];
+
+		if (!empty($this->hooks[$class][$function]))
+		{
+			// Developer tries to call a hooked function within the hooked function... 
+			if ($this->current_hook !== NULL && $this->current_hook['class'] === $class && $this->current_hook['function'] === $function)
+			{
+				return false;
+			}
+
+			// Call the hook with the arguments attached and store result
+			$arguments = func_get_args();
+			$this->current_hook = array('class' => $class, 'function' => $function);
+			$arguments[0] = &$this;
+
+			// Call the hook chain...
+			if (isset($this->hooks[$class][$function]['standalone']))
+			{
+				$this->hook_result[$class][$function] = call_user_func_array($this->hooks[$class][$function]['standalone'], $arguments);
+			}
+			else
+			{
+				foreach (array('first', 'normal', 'last') as $mode)
+				{
+					if (!isset($this->hooks[$class][$function][$mode]))
+					{
+						continue;
+					}
+
+					foreach ($this->hooks[$class][$function][$mode] as $hook)
+					{
+						$this->hook_result[$class][$function] = call_user_func_array($hook, $arguments);
+					}
+				}
+			}
+
+			$this->current_hook = NULL;
+			return true;
+		}
+
+		$this->current_hook = NULL;
+		return false;
+	}
+
+	/**
+	* Get result from previously called functions/methods for the same hook
+	*
+	* @param mixed $definition Declaring function (with __FUNCTION__) or class with array(get_class(), __FUNCTION)
+	* @return mixed False if nothing returned if there is no result, else array('result' => ... )
+	*/
+	function previous_hook_result($definition)
+	{
+		$class = (!is_array($definition)) ? '__global' : $definition[0];
+		$function = (!is_array($definition)) ? $definition : $definition[1];
+
+		if (!empty($this->hooks[$class][$function]) && isset($this->hook_result[$class][$function]))
+		{
+			return array('result' => $this->hook_result[$class][$function]);
+		}
+
+		return false;
+	}
+
+	/**
+	* Check if the called functions/methods returned something.
+	*
+	* @param mixed $definition Declaring function (with __FUNCTION__) or class with array(get_class(), __FUNCTION)
+	* @return bool True if results are there, false if not
+	*/
+	function hook_return($definition)
+	{
+		$class = (!is_array($definition)) ? '__global' : $definition[0];
+		$function = (!is_array($definition)) ? $definition : $definition[1];
+
+		if (!empty($this->hooks[$class][$function]) && isset($this->hook_result[$class][$function]))
+		{
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	* Give actual result from called functions/methods back.
+	*
+	* @param mixed $definition Declaring function (with __FUNCTION__) or class with array(get_class(), __FUNCTION)
+	* @return mixed The result
+	*/
+	function hook_return_result($definition)
+	{
+		$class = (!is_array($definition)) ? '__global' : $definition[0];
+		$function = (!is_array($definition)) ? $definition : $definition[1];
+
+		if (!empty($this->hooks[$class][$function]) && isset($this->hook_result[$class][$function]))
+		{
+			$result = $this->hook_result[$class][$function];
+			unset($this->hook_result[$class][$function]);
+			return $result;
+		}
+
+		return;
+	}
+
+	/**
+	* Add new function to the allowed hooks.
+	*
+	* @param mixed $definition Declaring function (with __FUNCTION__) or class with array(get_class(), __FUNCTION)
+	*/
+	function add_hook($definition)
+	{
+		if (!is_array($definition))
+		{
+			$definition = array('__global', $definition);
+		}
+
+		$this->hooks[$definition[0]][$definition[1]] = array();
+	}
+
+	/**
+	* Remove function from the allowed hooks.
+	*
+	* @param mixed $definition Declaring function (with __FUNCTION__) or class with array(get_class(), __FUNCTION)
+	*/
+	function remove_hook($definition)
+	{
+		$class = (!is_array($definition)) ? '__global' : $definition[0];
+		$function = (!is_array($definition)) ? $definition : $definition[1];
+
+		if (isset($this->hooks[$class][$function]))
+		{
+			unset($this->hooks[$class][$function]);
+
+			if (isset($this->hook_result[$class][$function]))
+			{
+				unset($this->hook_result[$class][$function]);
+			}
+		}
+	}
+}
+
+?>
+\ No newline at end of file
diff --git a/phpBB/includes/session.php b/phpBB/includes/session.php
index d9cc85a154..cbb70e8601 100644
--- a/phpBB/includes/session.php
+++ b/phpBB/includes/session.php
@@ -1518,6 +1518,10 @@ class user extends session
 			}
 		}
 
+		// Call phpbb_user_session_handler() in case external application want to "bend" some variables or replace classes...
+		// After calling it we continue script execution...
+		phpbb_user_session_handler();
+
 		// If this function got called from the error handler we are finished here.
 		if (defined('IN_ERROR_HANDLER'))
 		{
diff --git a/phpBB/includes/template.php b/phpBB/includes/template.php
index b13dbaa99a..ca118fb632 100644
--- a/phpBB/includes/template.php
+++ b/phpBB/includes/template.php
@@ -147,7 +147,16 @@ class template
 	*/
 	function display($handle, $include_once = true)
 	{
-		global $user;
+		global $user, $phpbb_hook;
+
+		// To let users change the complete templated page (all variables available)
+		if ($phpbb_hook->call_hook(array(get_class(), __FUNCTION__), $handle, $include_once))
+		{
+			if ($phpbb_hook->hook_return(array(get_class(), __FUNCTION__)))
+			{
+				return $phpbb_hook->hook_return_result(array(get_class(), __FUNCTION__));
+			}
+		}
 
 		if (defined('IN_ERROR_HANDLER'))
 		{