documenting and adding exception and redirect handler to json handler

json.php

@@ -1,16 +1,29 @@
 <?php
 /**
- * eGroupWare - JSON gateway
+ * eGroupWare - general JSON handler for EGroupware
  *
  * @link http://www.egroupware.org
  * @license http://opensource.org/licenses/gpl-license.php GPL - GNU General Public License
  * @package api
  * @subpackage ajax
- * @author Andreas Stoeckel
+ * @author Andreas Stoeckel <as@stylite.de>
  * @version $Id$
  */
 
-require_once('./phpgwapi/inc/class.egw_json.inc.php');
+/**
+ * callback if the session-check fails, redirects via xajax to login.php
+ *
+ * @param array &$anon_account anon account_info with keys 'login', 'passwd' and optional 'passwd_type'
+ * @return boolean/string true if we allow anon access and anon_account is set, a sessionid or false otherwise
+ */
+function xajax_redirect(&$anon_account)
+{
+	$response = new egw_json_response();
+	$response->redirect($GLOBALS['egw_info']['server']['webserver_url'].'/login.php?cd=10');
+	$response->printOutput();
+
+	common::egw_exit();
+}
 
 /**
  * Exception handler for xajax, return the message (and trace, if enabled) as alert() to the user
@@ -21,7 +34,27 @@ require_once('./phpgwapi/inc/class.egw_json.inc.php');
  */
 function ajax_exception_handler(Exception $e)
 {
-	//Exceptions should be returned
+	// logging all exceptions to the error_log
+	if (function_exists('_egw_log_exception'))
+	{
+		_egw_log_exception($e,$message);
+	}
+	$response = new egw_json_response();
+	$message .= ($message ? "\n\n" : '').$e->getMessage();
+	
+	// only show trace (incl. function arguments) if explicitly enabled, eg. on a development system
+	if ($GLOBALS['egw_info']['server']['exception_show_trace'])
+	{
+		$message .= "\n\n".$e->getTraceAsString();
+	}
+	$response->addAlert($message);
+	$response->printOutput();
+
+	if (is_object($GLOBALS['egw']))
+	{
+		common::egw_exit();
+	}
+	exit;
 }
 
 // set our own exception handler, to not get the html from eGW's default one
@@ -58,9 +91,7 @@ if (isset($_GET['menuaction']))
 
 	//Check whether the request data is set
 	$json->parseRequest($_GET['menuaction'], (array)$_POST['json_data']);
-	exit;
+	common::egw_exit();
 }
 
-throw new Exception($_SERVER['PHP_SELF'] . "Invalid AJAX JSON Request");
+throw new Exception($_SERVER['PHP_SELF'] . ' Invalid AJAX JSON Request');
-
-

phpgwapi/inc/class.egw_json.inc.php

@@ -6,18 +6,23 @@
  * @license http://opensource.org/licenses/gpl-license.php GPL - GNU General Public License
  * @package api$request['menuaction'], $parameters
  * @subpackage ajax
- * @author Andreas Stoeckel
+ * @author Andreas Stoeckel <as@stylite.de>
  * @version $Id$
  */
 
-/* Class which handles JSON requests to the server */
+/**
+ * Class handling JSON requests to the server 
+ */
 class egw_json_request
 {
-	/* Parses the raw input data supplied with the input_data parameter and calls the
+	/**
-	callback function, passing the "menuaction" and all parameters supplied in the request to it.
+	 * Parses the raw input data supplied with the input_data parameter and calls the menuaction
-	@param string $input_data is the RAW input data as it was received from the client
+	 * passing all parameters supplied in the request to it.
-	@param callback $callback(string $menuaction, array $parameters) called when a valid request has been received. The result of the callback function will be returned by parseRequest
+	 * 
-	@returns NULL if parsing the request failed, or the result of the callback function if the request has been successfully decoded.*/
+	 * @param string menuaction to call
+	 * @param string $input_data is the RAW input data as it was received from the client
+	 * @returns NULL if parsing the request failed, or the result of the callback function if the request has been successfully decoded.
+	 */
 	public function parseRequest($menuaction, $input_data)
 	{
 		if (empty($input_data))
@@ -27,7 +32,7 @@ class egw_json_request
 		else
 		{
 			//Decode the JSON input data into associative arrays		
-			if ($json = json_decode(stripslashes($input_data[0]), true))
+			if (($json = json_decode(stripslashes($input_data[0]), true)))
 			{
 				//Get the request array
 				if (isset($json['request']))
@@ -48,7 +53,13 @@ class egw_json_request
 		return NULL;
 	}
 
-	public function handleRequest($menuaction, $parameters)
+	/**
+	 * Request handler
+	 * 
+	 * @param string $menuaction
+	 * @param array $parameters
+	 */
+	public function handleRequest($menuaction, array $parameters)
 	{
 		if (strpos($menuaction,'::') !== false && strpos($menuaction,'.') === false)	// static method name app_something::method
 		{
@@ -113,18 +124,39 @@ class egw_json_request
 	}
 }
 
+/**
+ * Class used to send ajax responses
+ */
 class egw_json_response
 {
-	/* A response can only contain one generic data part. This variable is used to
+	/**
-	store, whether a data part had already been added to the response.*/
+	 * A response can only contain one generic data part. 
+	 * This variable is used to store, whether a data part had already been added to the response.
+	 *  
+	 * @var boolean
+	 */
 	private $hasData = false;
 
-	/* Holds the actual response data which is then encoded to JSON once the "getJSON"
+	/**
-	function is called */
+	 * Holds the actual response data which is then encoded to JSON 
+	 * once the "getJSON" function is called
+	 * 
+	 * @var array
+	 */
 	protected $responseArray = array();
 
+	/**
+	 * Holding instance of class for singelton egw_json_response::get()
+	 * 
+	 * @var egw_json_response
+	 */
 	private static $response = null;
 
+	/**
+	 * Singelton for class
+	 * 
+	 * @return egw_json_response
+	 */
 	public static function get()
 	{
 		if (!isset(self::$response))
@@ -134,31 +166,50 @@ class egw_json_response
 		return self::$response;
 	}
 
-	/* Private function used to send the HTTP header of the JSON response */
+	/**
+	 * Private function used to send the HTTP header of the JSON response
+	 */
 	private function sendHeader()
 	{
 		//Send the character encoding header
 		header('content-type: application/json; charset='.translation::charset());
 	}
 
-	/* Privade function which is used to send the result via HTTP */
+	/**
-	private function sendResult()
+	 * Private function which is used to send the result via HTTP
+	 */
+	public function sendResult()
 	{
 		$this->sendHeader();
 		echo $this->getJSON();
 	}
 	
-	/* Adds any type of data to the response array */
+	/**
+	 * xAjax compatibility function
+	 */
+	public function printOutput()
+	{
+		// do nothing, as output is triggered by destructor
+	}
+
+	/**
+	 * Adds any type of data to the response array
+	 */
 	protected function addGeneric($key, $data)
 	{
 		$this->responseArray[] = array(
-			"type" => $key,
+			'type' => $key,
-			"data" => $data);
+			'data' => $data,
+		);
 	}
 
-	/* Adds a "data" response to the json response. This function may only be called once
+	/**
-	for a single JSON response object.
+	 * Adds a "data" response to the json response. 
-	@param object/array/string $data can be of any data type and will be added JSON Encoded to your response.*/
+	 * 
+	 * This function may only be called once for a single JSON response object.
+	 * 
+	 * @param object|array|string $data can be of any data type and will be added JSON Encoded to your response.
+	 */
 	public function data($data)
 	{
 		/* Only allow adding the data response once */
@@ -173,10 +224,14 @@ class egw_json_response
 		}
 	}
 
-	/* Adds an "alert" to the response which can be handeled on the client side. The default implementation simply displays
+	/**
-	the text supplied here with the JavaScript function "alert".
+	 * Adds an "alert" to the response which can be handeled on the client side. 
-	@param string $message contains the actual message being sent to the client.
+	 * 
-	@param string $details (optional) can be used to inform the user on the client side about additional details about the error. This might be information how the error can be resolved/why it was raised or simply some debug data.*/
+	 * The default implementation simply displays the text supplied here with the JavaScript function "alert".
+	 * 
+	 * @param string $message contains the actual message being sent to the client.
+	 * @param string $details (optional) can be used to inform the user on the client side about additional details about the error. This might be information how the error can be resolved/why it was raised or simply some debug data.
+	 */
 	public function alert($message, $details = '')
 	{
 		if (is_string($message) && is_string($details))
@@ -191,9 +246,12 @@ class egw_json_response
 		}
 	}
 
-	/* Allows you to add a generic java script to the response which will be executed upon the request gets received. Deprecated.
+	/**
-	@deprecated
+	 * Allows to add a generic java script to the response which will be executed upon the request gets received.
-	@param string $script the script code which should be executed upon receiving*/	
+	 * 
+	 * @deprecated
+	 * @param string $script the script code which should be executed upon receiving
+	 */	
 	public function script($script)
 	{
 		if (is_string($script))
@@ -206,19 +264,23 @@ class egw_json_response
 		}
 	}
 
-	/* Adds an html assign to the response, which is excecuted upon the request is received. Deprecated, just for compatibility with XAJAX
+	/**
-	@deprecated
+	 * Adds an html assign to the response, which is excecuted upon the request is received.
-	@param string $id the identifier of the html element in which the assign shall take place
+	 *  
-	@param string $key the key in the html element which should be modified when the assign takes place.
+	 * @deprecated just for compatibility with XAJAX
-	@param string $value the value which should be assigned to the given key*/
+	 * @param string $id id of dom element to modify
+	 * @param string $key attribute name of dom element which should be modified
+	 * @param string $value the value which should be assigned to the given attribute
+	 */
 	public function assign($id, $key, $value)
 	{
 		if (is_string($id) && is_string($key) && (is_string($value) || is_numeric($value)))
 		{
 			$this->addGeneric('assign', array(
-				"id" => $id,
+				'id' => $id,
-				"key" => $key,
+				'key' => $key,
-				"value" => $value));
+				'value' => $value,
+			));
 		}
 		else
 		{
@@ -226,14 +288,32 @@ class egw_json_response
 		}
 	}
 	
-	/* Returns the actual JSON code generated by calling the above "add" function.*/	
+	/**
+	 * Redirect to given url
+	 * 
+	 * @param string $url
+	 */
+	public function redirect($url)
+	{
+		self::script("location.href = '$url';");
+	}
+
+	/**
+	 * Returns the actual JSON code generated by calling the above "add" function.
+	 * 
+	 * @return string
+	 */	
 	public function getJSON()
 	{
 		/* Wrap the result array into a parent "response" Object */
-		$res['response'] = $this->responseArray;
+		$res = array('response' => $this->responseArray);
+		
 		return json_encode($res, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP);
 	}
 
+	/**
+	 * Destructor
+	 */
 	public function __destruct()
 	{
 		$this->sendResult();

phpgwapi/js/egw_json.js

@@ -5,8 +5,8 @@
  * @license http://opensource.org/licenses/gpl-license.php GPL - GNU General Public License
  * @package api
  * @subpackage ajax
- * @author Andreas Stoeckel
+ * @author Andreas Stoeckel <as@stylite.de>
- * @version $Id:$
+ * @version $Id$
  */
 
 /* The egw_json_request is the javaScript side implementation of class.egw_json.inc.php.*/