egroupware/phpgwapi/inc/class.egw_json.inc.php

<?php
/**
 * eGroupWare API: JSON - Contains functions and classes for doing JSON requests.
 *
 * @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
 * @version $Id:$
 */

/* Class which handles 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.
	@param string $input_data is the RAW input data as it was received from the client
	@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.*/
	public function parseRequest($input_data, $callback)
	{
		//Decode the JSON input data into associative arrays		
		if ($json = json_decode(stripslashes($input_data), true))
		{
			//Get the request array
			if (isset($json['request']))
			{
				$request = $json['request'];
				
				//Check whether the "menuaction" string exists
				if (isset($request['menuaction']))
				{
					//Check whether any parameters were supplied along with the request
					$parameters = array();
					if (isset($request['parameters']))
						$parameters = $request['parameters'];

					//Call the supplied callback function along with the menuaction and the passed parameters
					return call_user_func($callback, $request['menuaction'], $parameters);
				}
			}
		}

		return NULL;
	}

}

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.*/
	private $hasData = false;

	/* Holds the actual response data which is then encoded to JSON once the "getJSON"
	function is called */
	protected $responseArray = array();

	/* Adds any type of data to the response array */
	protected function addGeneric($key, $data)
	{
		$this->responseArray[] = array(
			"type" => $key,
			"data" => $data);
	}

	/* Adds a "data" response to the json 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 addData($data)
	{
		/* Only allow adding the data response once */
		if (!$this->hasData)
		{
			$this->addGeneric('data', $data);
			$this->hasData = true;
		}
		else
		{
			throw new Exception("Adding more than one data response to a JSON response is not allowed.");
		}
	}

	/* 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".
	@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 addAlert($message, $details = '')
	{
		if (is_string($message) && is_string($details))
		{
			$this->addGeneric('alert', array(
				"message" => $message,
				"details" => $details));
		}
		else
		{
			throw new Exception("Invalid parameters supplied.");
		}
	}

	/* Allows you to add a generic java script to the response which will be executed upon the request gets received. Deprecated.
	@deprecated
	@param string $script the script code which should be executed upon receiving*/	
	public function addScript($script)
	{
		if (is_string($script))
		{
			$this->addGeneric('script', $script);
		}
		else
		{
			throw new Exception("Invalid parameters supplied.");
		}
	}

	/* Adds an html assign to the response, which is excecuted upon the request is received. Deprecated, just for compatibility with XAJAX
	@deprecated
	@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.
	@param string $value the value which should be assigned to the given key*/
	public function addAssign($id, $key, $value)
	{
		if (is_string($id) && is_string($key) && (is_string($value) || is_numeric($value)))
		{
			$this->addGeneric('assign', array(
				"id" => $id,
				"key" => $key,
				"value" => $value));
		}
		else
		{
			throw new Exception("Invalid parameters supplied");
		}
	}

	/* Returns the actual JSON code generated by calling the above "add" function.*/	
	public function getJSON()
	{
		/* Wrap the result array into a parent "response" Object */
		$res['response'] = $this->responseArray;
		return json_encode($res, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP);
	}
}