save result of last hook into class variable

inc/inc.ClassControllerCommon.php

@@ -35,6 +35,12 @@ class SeedDMS_Controller_Common {
 	 */
 	protected $errormsg;
 
+	/**
+	 * @var mixed $lasthookresult result of last hook
+	 * @access protected
+	 */
+	protected $lasthookresult;
+
 	function __construct($params) {
 		$this->params = $params;
 		$this->error = 0;
@@ -132,22 +138,59 @@ class SeedDMS_Controller_Common {
 	} /* }}} */
 
 	/**
-	 * Call a controller hook
+	 * Call all hooks registered for a controller
 	 *
-	 * If a hook returns false, then no other hook will be called, because the
+	 * Executes all hooks registered for the current controller.
+	 * A hook is just a php function which is passed the current controller and
+	 * additional paramaters passed to this method.
+	 *
+	 * If a hook returns false, then no other hook will be called, because this
 	 * method returns right away. If hook returns null, then this is treated like
-	 * it was never called and the default action is executed. Any other value
-	 * returned by the hook will be returned by this method.
+	 * it was never called and the next hook is called. Any other value
+	 * returned by a hook will be temporarily saved (possibly overwriting a value
+	 * from a previously called hook) and the next hook is called.
+	 * The temporarily saved return value is eventually returned by this method
+	 * when all hooks are called and no following hook failed.
+	 * The temporarily saved return value is also saved in a protected class
+	 * variable $lasthookresult which is initialized to null. This could be used
+	 * by following hooks to check if preceding hook did already succeed.
+	 *
+	 * Consider that a failing hook (returns false) will imediately quit this
+	 * function an return false, even if a formerly called hook has succeeded.
+	 * Also consider, that a second succeeding hook will overwrite the return value
+	 * of a previously called hook.
+	 * Third, keep in mind that there is no predefined order of hooks.
+	 *
+	 * Example 1: Assuming the hook 'loginRestrictions' in the 'Login' controller
+	 * is implemented by two extensions.
+	 * One extension restricts login to a certain time of the day and a second one
+	 * checks the strength of the password. If the password strength is to low, it
+	 * will prevent login. If the hook in the first extension allows login (returns true)
+	 * and the second doesn't (returns false), then this method will return false.
+	 * If the hook in the second extension doesn't care and therefore returns null, then
+	 * this method will return true.
+	 *
+	 * Example 2: Assuming the hook 'authenticate' in the 'Login' controller
+	 * is implemented by two extensions. This hook must return false if authentication
+	 * fails, null if the hook does not care, or a
+	 * valid user in case of a successful authentication.
+	 * If the first extension is able to authenticate the user, the hook in the second
+	 * extension will still be called and could fail. So the return value of this
+	 * method is false. The second hook could actually succeed as well and return a
+	 * different user than the first hook which will eventually be returned by this
+	 * method. The last hook will always win. If you need to know if a previously
+	 * called hook succeeded, you can check the class variable $lasthookresult in the
+	 * hook.
 	 *
 	 * @param $hook string name of hook
 	 * @return mixed false if one of the hooks fails,
-	 *               true if all hooks succedded,
+	 *               true/value if all hooks succedded,
 	 *               null if no hook was called
 	 */
 	function callHook($hook) { /* {{{ */
 		$tmp = explode('_', get_class($this));
 		if(isset($GLOBALS['SEEDDMS_HOOKS']['controller'][lcfirst($tmp[2])])) {
-			$r = null;
+			$this->lasthookresult = null;
 			foreach($GLOBALS['SEEDDMS_HOOKS']['controller'][lcfirst($tmp[2])] as $hookObj) {
 				if (method_exists($hookObj, $hook)) {
 					switch(func_num_args()) {
@@ -165,11 +208,11 @@ class SeedDMS_Controller_Common {
 						return $result;
 					}
 					if($result !== null) {
-						$r = $result;
+						$this->lasthookresult = $result;
 					}
 				}
 			}
-			return $r;
+			return $this->lasthookresult;
 		}
 		return null;
 	} /* }}} */