Peter M. Groen / knowledgetree

Commit 8168e5f6775dd901ac04e231ff85ad7f5d036463

Authored by Megan Watson 2009-02-03 12:45:08 +0000

Added a new webservice layer that implements a REST framework.

Committed by: Megan Watson
Reviewed by: Donald Jackson



git-svn-id: https://kt-dms.svn.sourceforge.net/svnroot/kt-dms/trunk@9768 c91229c3-7414-0410-bfa2-8a42b809f60b

Inline Side-by-side

Showing 1 changed file with 622 additions and 0 deletions

ktwebservice/KTWebService.php 0 → 100644

View file @8168e5f

	1	+<?php
	2	+/**
	3	+ * Framework for a rest server
	4	+ *
	5	+ * KnowledgeTree Community Edition
	6	+ * Document Management Made Simple
	7	+ * Copyright (C) 2008, 2009 KnowledgeTree Inc.
	8	+ * Portions copyright The Jam Warehouse Software (Pty) Limited
	9	+ *
	10	+ * This program is free software; you can redistribute it and/or modify it under
	11	+ * the terms of the GNU General Public License version 3 as published by the
	12	+ * Free Software Foundation.
	13	+ *
	14	+ * This program is distributed in the hope that it will be useful, but WITHOUT
	15	+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
	16	+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
	17	+ * details.
	18	+ *
	19	+ * You should have received a copy of the GNU General Public License
	20	+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
	21	+ *
	22	+ * You can contact KnowledgeTree Inc., PO Box 7775 #87847, San Francisco,
	23	+ * California 94120-7775, or email info@knowledgetree.com.
	24	+ *
	25	+ * The interactive user interfaces in modified source and object code versions
	26	+ * of this program must display Appropriate Legal Notices, as required under
	27	+ * Section 5 of the GNU General Public License version 3.
	28	+ *
	29	+ * In accordance with Section 7(b) of the GNU General Public License version 3,
	30	+ * these Appropriate Legal Notices must retain the display of the "Powered by
	31	+ * KnowledgeTree" logo and retain the original copyright notice. If the display of the
	32	+ * logo is not reasonably feasible for technical reasons, the Appropriate Legal Notices
	33	+ * must display the words "Powered by KnowledgeTree" and retain the original
	34	+ * copyright notice.
	35	+ * Contributor( s): ______________________________________
	36	+ *
	37	+ */
	38	+
	39	+require_once('../config/dmsDefaults.php');
	40	+require_once('../ktapi/ktapi.inc.php');
	41	+
	42	+/**
	43	+ * Base class for encoding the request response
	44	+ *
	45	+ * @author KnowledgeTree Team
	46	+ * @package KTWebService
	47	+ * @version Version 0.9
	48	+ */
	49	+class EncoderBase
	50	+{
	51	+ /**
	52	+ * Constructor for the base encoder
	53	+ *
	54	+ * @author KnowledgeTree Team
	55	+ * @access public
	56	+ */
	57	+ public function __construct()
	58	+ {
	59	+ }
	60	+
	61	+ /**
	62	+ * Gets the encoder based on type - XML or JSON
	63	+ *
	64	+ * @author KnowledgeTree Team
	65	+ * @access public
	66	+ * @static
	67	+ * @param string $type The type of encoder - xml\|json
	68	+ * @return EncoderBase
	69	+ */
	70	+ public static function getEncoder($type)
	71	+ {
	72	+ $encoder = ucwords(strtolower($type)) . 'Encoder';
	73	+ return new $encoder();
	74	+ }
	75	+
	76	+ /**
	77	+ * Performs the encoding
	78	+ *
	79	+ * @author KnowledgeTree Team
	80	+ * @access public
	81	+ * @param mixed $input The response to be encoded
	82	+ * @return string
	83	+ */
	84	+ public function encode($input)
	85	+ {
	86	+ return $input;
	87	+ }
	88	+
	89	+ /**
	90	+ * Returns the headers associated with the encoding
	91	+ *
	92	+ * @author KnowledgeTree Team
	93	+ * @access public
	94	+ * @return array
	95	+ */
	96	+ public function getHeaders()
	97	+ {
	98	+ return array();
	99	+ }
	100	+}
	101	+
	102	+/**
	103	+ * Encodes the response output using json
	104	+ *
	105	+ * @author KnowledgeTree Team
	106	+ * @package KTWebService
	107	+ * @version Version 0.9
	108	+ */
	109	+class JsonEncoder extends EncoderBase
	110	+{
	111	+ /**
	112	+ * Serialises the response using json
	113	+ *
	114	+ * @author KnowledgeTree Team
	115	+ * @access public
	116	+ * @param mixed $input The response to be serialised
	117	+ * @return string The JSON string
	118	+ */
	119	+ public function encode($input)
	120	+ {
	121	+ return json_encode($input);
	122	+ }
	123	+}
	124	+
	125	+/**
	126	+ * Encodes the response output in XML
	127	+ *
	128	+ * @author KnowledgeTree Team
	129	+ * @package KTWebService
	130	+ * @version Version 0.9
	131	+ */
	132	+class XmlEncoder extends EncoderBase
	133	+{
	134	+ /**
	135	+ * Formats the output as XML
	136	+ *
	137	+ * @author KnowledgeTree Team
	138	+ * @access public
	139	+ * @param array $input The response to be formatted
	140	+ * @return string The XML
	141	+ */
	142	+ public function encode($input)
	143	+ {
	144	+ if(is_string($input)){
	145	+ $input = array($input);
	146	+ }
	147	+
	148	+ if(!is_array($input)){
	149	+ // throw exception
	150	+ return false;
	151	+ }
	152	+
	153	+ $xml = '<?xml version="1.0">'."\n";
	154	+ $xml .= '<response-status="ok">'."\n";
	155	+
	156	+ $xml .= XmlEncoder::createXmlFromArray($input);
	157	+
	158	+ return $xml;
	159	+ }
	160	+
	161	+ /**
	162	+ * Creates an XML string from an array
	163	+ *
	164	+ * @author KnowledgeTree Team
	165	+ * @access private
	166	+ * @param array $input The array to be formatted
	167	+ * @return string The XML
	168	+ */
	169	+ private static function createXmlFromArray($input)
	170	+ {
	171	+ $xml = '';
	172	+ foreach ($input as $key => $value) {
	173	+
	174	+ if(is_array($value)){
	175	+ $value = XmlEncoder::createXmlFromArray($value);
	176	+ }
	177	+
	178	+ $xml .= "<$key>$value</$key>";
	179	+ }
	180	+ return $xml;
	181	+ }
	182	+
	183	+ /**
	184	+ * Returns the xml headers
	185	+ *
	186	+ * @author KnowledgeTree Team
	187	+ * @access public
	188	+ * @return array The headers as an array
	189	+ */
	190	+ public function getHeaders()
	191	+ {
	192	+ $headers = array();
	193	+ $headers['Content-type'] = 'text/xml';
	194	+ return $headers;
	195	+ }
	196	+}
	197	+
	198	+/**
	199	+ * Base class for the request response
	200	+ *
	201	+ * @author KnowledgeTree Team
	202	+ * @package KTWebService
	203	+ * @version Version 0.9
	204	+ */
	205	+class ResponseBase
	206	+{
	207	+ /**
	208	+ * The formatting to be used in the response
	209	+ *
	210	+ * @access protected
	211	+ * @var string xml\|json
	212	+ */
	213	+ protected $responseType;
	214	+
	215	+ /**
	216	+ * Create the response and set the type.
	217	+ *
	218	+ * @author KnowledgeTree Team
	219	+ * @access public
	220	+ * @param string $type xml\|json
	221	+ */
	222	+ public function __construct($type = 'xml')
	223	+ {
	224	+ $this->responseType = $type;
	225	+ }
	226	+
	227	+ /**
	228	+ * Dispatch function for calling the appropriate request method
	229	+ *
	230	+ * @author KnowledgeTree Team
	231	+ * @access public
	232	+ * @param string $method The request method - get\|post\|put\|delete
	233	+ * @param array $args The request arguments / parameters
	234	+ * @return bool FALSE on fail
	235	+ */
	236	+ public function _dispatch($method, $args)
	237	+ {
	238	+ $dispatch_method = "_{$method}";
	239	+ if(!is_callable(array($this, $dispatch_method))) {
	240	+ $this->_respondError("501 Not Implemented");
	241	+ return false;
	242	+ }
	243	+
	244	+ $this->{$dispatch_method}($args);
	245	+ }
	246	+
	247	+ /**
	248	+ * returns the protocol used in the request
	249	+ *
	250	+ * @author KnowledgeTree Team
	251	+ * @access protected
	252	+ * @return string
	253	+ */
	254	+ protected function _getProtocol()
	255	+ {
	256	+ $protocol = "HTTP/1.1";
	257	+ if(isset($_SERVER['SERVER_PROTOCOL'])) {
	258	+ $protocol = $_SERVER['SERVER_PROTOCOL'];
	259	+ }
	260	+ return $protocol;
	261	+ }
	262	+
	263	+ /**
	264	+ * Sets the error header
	265	+ *
	266	+ * @author KnowledgeTree Team
	267	+ * @access protected
	268	+ * @param string $error
	269	+ */
	270	+ protected function _respondError($error)
	271	+ {
	272	+ $protocol = $this->_getProtocol();
	273	+ header("$protocol $error");
	274	+ }
	275	+
	276	+ /**
	277	+ * Sets the response headers and body
	278	+ *
	279	+ * @author KnowledgeTree Team
	280	+ * @access protected
	281	+ * @param string $body The body of the response
	282	+ * @param array $headers The headers for the response
	283	+ */
	284	+ protected function _respond($body, $headers = array())
	285	+ {
	286	+ foreach($headers AS $header => $value) {
	287	+ header("{$header}: {$value}");
	288	+ }
	289	+ echo $body;
	290	+ }
	291	+}
	292	+
	293	+/**
	294	+ * Request response class - takes the input request and creates the response
	295	+ *
	296	+ * @author KnowledgeTree Team
	297	+ * @package KTWebService
	298	+ * @version Version 0.9
	299	+ */
	300	+class Response extends ResponseBase
	301	+{
	302	+ protected $output;
	303	+ protected $headers;
	304	+
	305	+ protected $error;
	306	+ protected $error_code;
	307	+
	308	+ protected $class;
	309	+ protected $method;
	310	+
	311	+ protected $ktapi;
	312	+
	313	+ /**
	314	+ * Creates the response with the given type
	315	+ *
	316	+ * @author KnowledgeTree Team
	317	+ * @access public
	318	+ * @param string $type xml\|json
	319	+ */
	320	+ public function __construct($type)
	321	+ {
	322	+ parent::__construct($type);
	323	+
	324	+ $this->class = 'KTAPI';
	325	+ }
	326	+
	327	+ /**
	328	+ * Parses the arguments for the method and parameters.
	329	+ * Uses reflection to determine the order of parameters and then runs the requested method.
	330	+ *
	331	+ * @author KnowledgeTree Team
	332	+ * @access protected
	333	+ * @param array $args The request arguments
	334	+ * @return array The result of the method
	335	+ */
	336	+ protected function callMethod($args)
	337	+ {
	338	+ $method = (isset($args['method'])) ? $args['method'] : '';
	339	+ $session_id = (isset($args['session_id'])) ? $args['session_id'] : NULL;
	340	+ unset($args['method']);
	341	+ unset($args['session_id']);
	342	+
	343	+ // Get the available methods in KTAPI
	344	+ $reflect = new ReflectionClass($this->class);
	345	+ $methods = $reflect->getMethods();
	346	+
	347	+ // Check that the method exists
	348	+ $exists = false;
	349	+ foreach ($methods as $var){
	350	+ if($var->getName() == $method){
	351	+ $exists = true;
	352	+ break;
	353	+ }
	354	+ }
	355	+
	356	+ if(!$exists){
	357	+ $this->error = 'Method does not exist in the API: '.$method;
	358	+ $this->error_code = 404;
	359	+ return false;
	360	+ }
	361	+
	362	+ $this->method = $method;
	363	+
	364	+ // Get method parameters
	365	+ $reflectMethod = new ReflectionMethod($this->class, $method);
	366	+ $methodParams = $reflectMethod->getParameters();
	367	+
	368	+ $orderedParams = array();
	369	+ // map parameters to supplied arguments and determine order
	370	+ foreach ($methodParams as $parameter){
	371	+ $param = isset($args[$parameter->getName()]) ? $args[$parameter->getName()] : '';
	372	+
	373	+ if(empty($param)) {
	374	+ if(!$parameter->isOptional()){
	375	+ $this->error = 'Missing required parameter: '.$parameter->getName();
	376	+ return false;
	377	+ }
	378	+ $param = $parameter->getDefaultValue();
	379	+ }
	380	+
	381	+ $orderedParams[$parameter->getPosition()] = $param;
	382	+ }
	383	+
	384	+ // instantiate KTAPI and invoke method
	385	+ $ktapi = $this->get_ktapi($session_id);
	386	+ $result = $reflectMethod->invokeArgs($ktapi, $orderedParams);
	387	+
	388	+ return $result;
	389	+ }
	390	+
	391	+ /**
	392	+ * Instantiate KTAPI and get the active session, if the session id is supplied
	393	+ *
	394	+ * @author KnowledgeTree Team
	395	+ * @access protected
	396	+ * @param string $session_id
	397	+ * @return KTAPI
	398	+ */
	399	+ protected function &get_ktapi($session_id = null)
	400	+ {
	401	+ if (!is_null($this->ktapi))
	402	+ {
	403	+ return $this->ktapi;
	404	+ }
	405	+
	406	+ $kt = new KTAPI();
	407	+
	408	+ // if the session id has been passed through - get the active session.
	409	+ if(!empty($session_id)){
	410	+ $session = $kt->get_active_session($session_id, null);
	411	+
	412	+ if ( PEAR::isError($session))
	413	+ {
	414	+ // return error / exception
	415	+ return false;
	416	+ }
	417	+ }
	418	+ $this->ktapi = $kt;
	419	+ return $kt;
	420	+ }
	421	+
	422	+ /**
	423	+ * Not sure what to do here yet
	424	+ * @todo
	425	+ *
	426	+ * @author KnowledgeTree Team
	427	+ * @access protected
	428	+ * @param unknown_type $input
	429	+ * @return unknown
	430	+ */
	431	+ protected function flattenInput($input)
	432	+ {
	433	+ //echo gettype($input);
	434	+
	435	+ if(is_array($input)){
	436	+ return $input;
	437	+ }
	438	+
	439	+ if(is_string($input)){
	440	+ return array($input);
	441	+ }
	442	+
	443	+ return $input;
	444	+ }
	445	+
	446	+ /**
	447	+ * Implements the GET. Returns a result for the given method.
	448	+ *
	449	+ * @author KnowledgeTree Team
	450	+ * @access protected
	451	+ * @param array $args The request arguments
	452	+ * @return bool FALSE if error
	453	+ */
	454	+ protected function _get($args)
	455	+ {
	456	+ $result = $this->callMethod($args);
	457	+
	458	+ // if an error occurred, initiate the error response
	459	+ if($result === false){
	460	+ return false;
	461	+ }
	462	+
	463	+ $result = $this->flattenInput($result);
	464	+
	465	+ $encoder = EncoderBase::getEncoder($this->responseType);
	466	+ $this->output = $encoder->encode($result);
	467	+ $this->headers = $encoder->getHeaders();
	468	+ }
	469	+
	470	+ /**
	471	+ * Implements the POST. Posts a set of parameters to a given method.
	472	+ *
	473	+ * @todo
	474	+ * @author KnowledgeTree Team
	475	+ * @access protected
	476	+ * @param array $args
	477	+ */
	478	+ protected function _post($args)
	479	+ {
	480	+ }
	481	+
	482	+ /**
	483	+ * Implements the PUT. Puts / creates a new resource.
	484	+ *
	485	+ * @todo
	486	+ * @author KnowledgeTree Team
	487	+ * @access protected
	488	+ * @param array $args
	489	+ */
	490	+ protected function _put($args)
	491	+ {
	492	+ }
	493	+
	494	+ /**
	495	+ * Implements the DELETE. Deletes a resource
	496	+ *
	497	+ * @todo
	498	+ * @author KnowledgeTree Team
	499	+ * @access protected
	500	+ * @param array $args
	501	+ */
	502	+ protected function _delete($args)
	503	+ {
	504	+ }
	505	+
	506	+ /**
	507	+ * Generates the response output / error output
	508	+ *
	509	+ * @author KnowledgeTree Team
	510	+ * @access public
	511	+ */
	512	+ public function output()
	513	+ {
	514	+ if(!empty($this->error)){
	515	+ $this->_respondError($this->error_code);
	516	+ echo $this->error;
	517	+ exit;
	518	+ }
	519	+
	520	+ $this->_respond($this->output, $this->headers);
	521	+ }
	522	+}
	523	+
	524	+/**
	525	+ * Webservice class - parses the request and initiates the response.
	526	+ *
	527	+ * @author KnowledgeTree Team
	528	+ * @package KTWebService
	529	+ * @version Version 0.9
	530	+ */
	531	+class WebService
	532	+{
	533	+ /**
	534	+ * Handles the output
	535	+ *
	536	+ * @access private
	537	+ * @var Response object
	538	+ */
	539	+ private $response;
	540	+
	541	+ /**
	542	+ * The requested method or function
	543	+ *
	544	+ * @access private
	545	+ * @var string
	546	+ */
	547	+ private $method;
	548	+
	549	+ /**
	550	+ * The request arguments and parameters
	551	+ *
	552	+ * @access private
	553	+ * @var array
	554	+ */
	555	+ private $arguments;
	556	+
	557	+ /**
	558	+ * Constructor for setting up the webservice
	559	+ *
	560	+ * @author KnowledgeTree Team
	561	+ * @access public
	562	+ */
	563	+ public function WebService()
	564	+ {
	565	+ // determine the method of request
	566	+ $this->method = strtolower($_SERVER['REQUEST_METHOD']);
	567	+
	568	+ // get the parameters / arguments based on the method
	569	+ $this->getArguments();
	570	+
	571	+ // Check the response type - xml / json
	572	+ $responseType = (isset($this->arguments['type'])) ? $this->arguments['type'] : 'xml';
	573	+ unset($this->arguments['type']);
	574	+
	575	+ // Set the output handler
	576	+ $this->response = new response($responseType);
	577	+ }
	578	+
	579	+ /**
	580	+ * Gets the arguments / parameters from the request
	581	+ *
	582	+ * @author KnowledgeTree Team
	583	+ * @access private
	584	+ */
	585	+ private function getArguments()
	586	+ {
	587	+ $arguments = array();
	588	+ switch ($this->method){
	589	+ case 'put':
	590	+ case 'delete':
	591	+ parse_str(file_get_contents('php://input'), $arguments);
	592	+ break;
	593	+ case 'post':
	594	+ $arguments = $_POST;
	595	+ break;
	596	+ case 'get':
	597	+ default:
	598	+ $arguments = $_GET;
	599	+ }
	600	+ $this->arguments = $arguments;
	601	+ }
	602	+
	603	+ /**
	604	+ * Dispatches the request
	605	+ *
	606	+ * @author KnowledgeTree Team
	607	+ * @access public
	608	+ */
	609	+ public function handle()
	610	+ {
	611	+ $this->response->_dispatch($this->method, $this->arguments);
	612	+ $this->response->output();
	613	+ }
	614	+}
	615	+
	616	+// Instantiate the webservice
	617	+$ws = new WebService();
	618	+$ws->handle();
	619	+
	620	+exit();
	621	+
	622	+?>
0	623	\ No newline at end of file
...	...