modernized and documented the hooks-class, phpgw_hooks --> egw_hooks

admin/inc/class.soapplications.inc.php

@@ -15,7 +15,7 @@
 	{
 		var $db;
 		var $applications_table = 'egw_applications';
-		var $hooks_table = 'phpgw_hooks';
+		var $hooks_table = 'egw_hooks';
 
 		function soapplications()
 		{

phpgwapi/inc/class.hooks.inc.php

@@ -4,6 +4,7 @@
 	* This file written by Dan Kuykendall <seek3r@phpgroupware.org>            *
 	* Allows applications to "hook" into each other                            *
 	* Copyright (C) 2000, 2001 Dan Kuykendall                                  *
+	* New method hooks and docu are written by <RalfBecker@outdoor-training.de>*
 	* -------------------------------------------------------------------------*
 	* This library is part of the eGroupWare API                               *
 	* http://www.egroupware.org/api                                            * 
@@ -23,25 +24,47 @@
 	
 	/* $Id$ */
 
-	/*!
+	/**
-	@class hooks
+	 * class which gives ability for applications to set and use hooks to communicate with each other
-	@abstract  class which gives ability for applications to set and use hooks to communicate with each other
+	 *
-	@author    Dan Kuykendall
+	 * Hooks need to be declared in the app's setup.inc.php file and they have to be registered
-	@copyright LGPL
+	 * (copied into the database) by 
-	@package   phpgwapi
+	 *	- installing or updating the app via setup or 
-	@access    public
+	 *	- running Admin >> register all hooks
+	 * As the hooks-class can get cached in the session (session-type PHP_RESTORE), you also have to log
+	 * out and in again, that your changes take effect.
+	 *
+	 * Hooks can either have two formats
+	 *	- new method hooks (prefered), which are methods of a class. You can pass parameters to the call and
+	 *	  they can return values. They get declared in setup.inc.php as: 
+	 *	  $setup_info['appname']['hooks']['location'] = 'app.class.method';
+	 *	- old type, which are included files. Values can only be passed by global values and they cant return anything.
+	 *	  Old declaration in setup.inc.php: 
+	 *	  $setup_info['appname']['hooks'][] = 'location';
+	 *
+	 * @author  Dan Kuykendall
+	 * @author  Ralf Becker <RalfBecker@outdoor-training.de> new method hooks
+	 * @license LGPL
+	 * @package phpgwapi
+	 * @access  public
 	 */
 
 	class hooks
 	{
 		var $found_hooks = Array();
-		var $db = '';
+		var $db;
+		var $table = 'egw_hooks';
 
-		function hooks($db='')
+		/**
+		 * constructor, reads and caches the complete hooks table
+		 *
+		 * @param object $db=null database class, if null we use $GLOBALS['egw']->db
+		 */
+		function hooks($db=null)
 		{
 			$this->db = $db ? $db : $GLOBALS['egw']->db;	// this is to allow setup to set the db
 
-			$this->db->query("SELECT hook_appname, hook_location, hook_filename FROM phpgw_hooks",__LINE__,__FILE__);
+			$this->db->select($this->table,'hook_appname,hook_location,hook_filename',false,__LINE__,__FILE__);
 			while( $this->db->next_record() )
 			{
 				$this->found_hooks[$this->db->f('hook_appname')][$this->db->f('hook_location')] = $this->db->f('hook_filename');
@@ -51,19 +74,18 @@
 			//echo '</pre>';
 		}
 		
-		/*!
+		/**
-		@function process
+		 * executes all the hooks (the user has rights to) for a given location 
-		@abstract executes all the hooks (the user has rights to) for a given location 
+		 *
-		@syntax process($args,$order='',$no_permission_check = False)
+		 * @param string/array $args location-name as string or array with keys location, order and 
-		@param $args location-name as string or array:
+		 *	further data to be passed to the hook, if its a new method-hook
-		@param $args['location'] location-name
+		 * @param array $order appnames (as value), which should be executes first
-		@param $order or $args['order'] array of appnames (as value), which should be executes first
+		 * @param boolean $no_permission_check if True execute all hooks, not only the ones a user has rights to
-		@param $args is passed to the hook, if its a new method-hook
+		 *	$no_permission_check should *ONLY* be used when it *HAS* to be. (jengo)
-		@param $no_permission_check if True execute all hooks, not only the ones a user has rights to
+		 * @return array with results of each hook call (with appname as key) and value:
-		@note $no_permission_check should *ONLY* be used when it *HAS* to be. (jengo)
+		 *	- False if no hook exists, 
-		@returns array with results of each hook call (with appname as key): \
+		 *	- True if old hook exists and
-			False if no hook exists, True if old hook exists \
+		 * 	- whatever the new method-hook returns (can be True or False too!).
-			and whatever the new method-hook returns (can be True or False too!).
 		 */
 		function process($args, $order = '', $no_permission_check = False)
 		{
@@ -106,18 +128,16 @@
 			return $results;
 		}
 
-		/*!
+		/**
-		@function single
+		 * executes a single hook of a given location and application
-		@abstract executes a single hook of a given location and application
+		 *
-		@syntax single($args,$appname='',$no_permission_check = False)
+		 * @param string/array $args location-name as string or array with keys location, appname and 
-		@param $args location-name as string or array:
+		 *	further data to be passed to the hook, if its a new method-hook
-		@param $args['location'] location-name
+		 * @param string $appname name of the app, which's hook to execute, if empty the current app is used
-		@param $appname or $args['appname'] name of the app, which's hook to execute, if empty the current app is used
+		 * @param boolean $no_permission_check if True execute all hooks, not only the ones a user has rights to
-		@param $args is passed to the hook, if its a new method-hook
+		 *	$no_permission_check should *ONLY* be used when it *HAS* to be. (jengo)
-		@param $no_permission_check if True execute all hooks, not only the ones a user has rights to
+		 * @param boolean $try_unregisterd If true, try to include old file-hook anyway (for setup)
-		@param $try_unregisterd If true, try to include old file-hook anyway (for setup)
+		 * @return mixed False if no hook exists, True if old hook exists and whatever the new method-hook returns (can be True or False too!).
-		@note $no_permission_check should *ONLY* be used when it *HAS* to be. (jengo)
-		@returns False if no hook exists, True if an old hook exist and whatever the new method-hook returns
 		 */
 		function single($args, $appname = '', $no_permission_check = False,$try_unregistered = False)
 		{
@@ -170,9 +190,11 @@
 			}
 		}
 
-		/*!
+		/**
-		@function count
+		 * loop through the applications and count the hooks
-		@abstract loop through the applications and count the hooks
+		 *
+		 * @param string $location location-name
+		 * @return int the number of found hooks
 		 */
 		function count($location)
 		{
@@ -187,9 +209,8 @@
 			return $count;
 		}
 		
-		/*! 
+		/**
-		@function read()
+		 * @deprecated currently not being used
-		@abstract currently not being used
 		 */
 		function read()
 		{
@@ -200,23 +221,24 @@
 			return $this->found_hooks;
 		}
 
-		/*!
+		/**
-		@function register_hooks
+		 * Register and/or de-register an application's hooks
-		@abstract Register and/or de-register an application's hooks
+		 *
-		@syntax register_hooks($appname,$hooks='')
+		 * First all existing hooks of $appname get deleted in the db and then the given ones get registered.
-		@param $appname	Application 'name' 
+		 *
-		@param $hooks array with hooks to register, eg $setup_info[$app]['hooks'] or not used for only deregister the hooks
+		 * @param string $appname Application 'name' 
+		 * @param array $hooks=null hooks to register, eg $setup_info[$app]['hooks'] or not used for only deregister the hooks
+		 * @return boolean false on error, true otherwise
 		 */
-		function register_hooks($appname,$hooks='')
+		function register_hooks($appname,$hooks=null)
 		{
 			if(!$appname)
 			{
 				return False;
 			}
-			$db_appname = $this->db->db_addslashes($appname);
+			$this->db->delete($this->table,array('hook_appname' => $appname),__LINE__,__FILE__);
-			$this->db->query("DELETE FROM phpgw_hooks WHERE hook_appname='$db_appname'",__LINE__,__FILE__);
 
-			if (!is_array($hooks))	// only deregister
+			if (!is_array($hooks) || !count($hooks))	// only deregister
 			{
 				return True;
 			}
@@ -233,16 +255,19 @@
 					$location = $hook;
 					$filename = "hook_$hook.inc.php";
 				}
-				$this->db->query("INSERT INTO phpgw_hooks (hook_appname,hook_location,hook_filename)".
+				$this->db->insert($this->table,array(
-					" VALUES ('$appname','$location','$filename')");
+					'hook_filename' => $filename,
+				),array(
+					'hook_appname'  => $appname,
+					'hook_location' => $location,
+				),__LINE__,__FILE__);
 			}
 			return True;
 		}
 
 		
-		/*!
+		/**
-		@function register_all_hooks
+		 * Register the hooks of all applications (used by admin)
-		@abstract Register the hooks of all applications (used by admin)
 		 */
 		function register_all_hooks()
 		{
@@ -259,4 +284,3 @@
 			}
 		}
 	}
-?>

phpgwapi/setup/setup.inc.php

@@ -13,8 +13,8 @@
 
 	/* Basic information about this app */
 	$setup_info['phpgwapi']['name']      = 'phpgwapi';
-	$setup_info['phpgwapi']['title']     = 'API';
+	$setup_info['phpgwapi']['title']     = 'eGroupWare API';
-	$setup_info['phpgwapi']['version']   = '1.0.1.021';
+	$setup_info['phpgwapi']['version']   = '1.0.1.022';
 	$setup_info['phpgwapi']['versions']['current_header'] = '1.28';
 	$setup_info['phpgwapi']['enable']    = 3;
 	$setup_info['phpgwapi']['app_order'] = 1;
@@ -28,7 +28,7 @@
 	$setup_info['phpgwapi']['tables'][]  = 'phpgw_sessions';
 	$setup_info['phpgwapi']['tables'][]  = 'phpgw_app_sessions';
 	$setup_info['phpgwapi']['tables'][]  = 'phpgw_access_log';
-	$setup_info['phpgwapi']['tables'][]  = 'phpgw_hooks';
+	$setup_info['phpgwapi']['tables'][]  = 'egw_hooks';
 	$setup_info['phpgwapi']['tables'][]  = 'egw_languages';
 	$setup_info['phpgwapi']['tables'][]  = 'egw_lang';
 	$setup_info['phpgwapi']['tables'][]  = 'phpgw_nextid';
@@ -55,8 +55,6 @@
 	$setup_info['phpgwapi']['tables'][]  = 'egw_syncmlsummary';
 	$setup_info['phpgwapi']['tables'][]  = 'egw_links';
 
-
-
 	/* Basic information about this app */
 	$setup_info['notifywindow']['name']      = 'notifywindow';
 	$setup_info['notifywindow']['title']     = 'Notify Window';
@@ -65,19 +63,3 @@
 	$setup_info['notifywindow']['app_order'] = 1;
 	$setup_info['notifywindow']['tables']    = '';
 	$setup_info['notifywindow']['hooks'][]   = 'home';
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

phpgwapi/setup/tables_current.inc.php

@@ -126,7 +126,7 @@
 			'ix' => array(),
 			'uc' => array()
 		),
-		'phpgw_hooks' => array(
+		'egw_hooks' => array(
 			'fd' => array(
 				'hook_id' => array('type' => 'auto','nullable' => False),
 				'hook_appname' => array('type' => 'varchar','precision' => '255'),

phpgwapi/setup/tables_update.inc.php

@@ -820,4 +820,15 @@
 
 		return $GLOBALS['setup_info']['phpgwapi']['currentver'] = '1.0.1.021';
 	}
+
+
+	$test[] = '1.0.1.021';
+	function phpgwapi_upgrade1_0_1_021()
+	{
+		$GLOBALS['egw_setup']->oProc->RenameTable('phpgw_hooks','egw_hooks');
+		$GLOBALS['egw_setup']->hooks_table = 'egw_hooks';
+
+		$GLOBALS['setup_info']['phpgwapi']['currentver'] = '1.0.1.022';
+		return $GLOBALS['setup_info']['phpgwapi']['currentver'];
+	}
 ?>

setup/inc/class.setup.inc.php

@@ -34,7 +34,7 @@
 		var $prefs_table        = 'phpgw_preferences';
 		var $lang_table         = 'egw_lang';
 		var $languages_table    = 'egw_languages';
-		var $hooks_table        = 'phpgw_hooks';
+		var $hooks_table        = 'egw_hooks';
 		var $cats_table         = 'egw_categories';
 		var $oProc;
 
@@ -626,15 +626,14 @@
 				return False;
 			}
 
-			if($this->alessthanb($setup_info['phpgwapi']['currentver'],'0.9.8pre5') && ($setup_info['phpgwapi']['currentver'] != ''))
+			if(!$this->hooks_table)	// No hooks table yet
 			{
-				/* No phpgw_hooks table yet. */
 				return False;
 			}
 
 			if (!is_object($this->hooks))
 			{
-				$this->hooks =& CreateObject('phpgwapi.hooks',$this->db);
+				$this->hooks =& CreateObject('phpgwapi.hooks',$this->db,$this->hooks_table);
 			}
 			$this->hooks->register_hooks($appname,$setup_info[$appname]['hooks']);
 		}
@@ -656,9 +655,8 @@
 		 */
 		function deregister_hooks($appname)
 		{
-			if($this->alessthanb($setup_info['phpgwapi']['currentver'],'0.9.8pre5'))
+			if(!$this->hooks_table)	// No hooks table yet
 			{
-				/* No phpgw_hooks table yet. */
 				return False;
 			}
 
@@ -670,7 +668,7 @@
 			//echo "DELETING hooks for: " . $setup_info[$appname]['name'];
 			if (!is_object($this->hooks))
 			{
-				$this->hooks =& CreateObject('phpgwapi.hooks',$this->db);
+				$this->hooks =& CreateObject('phpgwapi.hooks',$this->db,$this->hooks_table);
 			}
 			$this->hooks->register_hooks($appname);
 		}
@@ -685,7 +683,7 @@
 		{
 			if (!is_object($this->hooks))
 			{
-				$this->hooks =& CreateObject('phpgwapi.hooks',$this->db);
+				$this->hooks =& CreateObject('phpgwapi.hooks',$this->db,$this->hooks_table);
 			}
 			return $this->hooks->single($location,$appname,True,True);
 		}