new hook system (do not get it confused with events or plugins please)

- introducing two new hookable functions too


git-svn-id: file:///svn/phpbb/trunk@8100 89ea8834-ac86-4346-8a33-228a782c2dd0

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;
+	}
 }
 
 ?>

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,20 +4336,45 @@ 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
 */

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]);
+			}
+		}
+	}
+}
+
+?>

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'))
 		{

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'))
 		{