Peter M. Groen / knowledgetree

Commit bab35d3be9f5bcf9b702e28772197661dbdeda41

Authored by Megan Watson
1 parent ee928212

Added php docblocks as documentation. 

Committed by: Megan Watson
Reviewed by: Kevin Cyster



git-svn-id: https://kt-dms.svn.sourceforge.net/svnroot/kt-dms/trunk@9718 c91229c3-7414-0410-bfa2-8a42b809f60b
Inline Side-by-side
Showing 1 changed file with 178 additions and 26 deletions
ktapi/KTAPISession.inc.php
  View file @bab35d3
1 1 <?php
2   -
3 2 /**
4   - * $Id$
5   - *
6 3 * KnowledgeTree Community Edition
7 4 * Document Management Made Simple
8 5 * Copyright (C) 2008, 2009 KnowledgeTree Inc.
... ... @@ -33,19 +30,80 @@
33 30 * logo is not reasonably feasible for technical reasons, the Appropriate Legal Notices
34 31 * must display the words "Powered by KnowledgeTree" and retain the original
35 32 * copyright notice.
36   - * Contributor( s): ______________________________________
37 33 *
  34 + * @copyright 2008-2009, KnowledgeTree Inc.
  35 + * @license GNU General Public License version 3
  36 + * @author KnowledgeTree Team
  37 + * @package KnowledgeTree API
  38 + * @version Version 0.9
38 39 */
39 40  
  41 +/**
  42 + * API for the handling the KnowledgeTree session
  43 + *
  44 + * @author KnowledgeTree Team
  45 + * @package KnowledgeTree API
  46 + * @version 0.9
  47 + */
40 48 class KTAPI_Session
41 49 {
42   - var $ktapi;
43   - var $user = null;
44   - var $session = '';
45   - var $sessionid = -1;
46   - var $active;
47   - var $origUserId;
  50 + /**
  51 + * This is a reference to the ktapi object.
  52 + *
  53 + * @access protected
  54 + * @var KTAPI
  55 + */
  56 + var $ktapi;
  57 +
  58 + /**
  59 + * This is a reference to the user object.
  60 + *
  61 + * @access protected
  62 + * @var User
  63 + */
  64 + var $user = null;
  65 +
  66 + /**
  67 + * This is a reference to the internal session object.
  68 + *
  69 + * @access protected
  70 + * @var Session
  71 + */
  72 + var $session = '';
  73 +
  74 + /**
  75 + * The sessionid from the database
  76 + *
  77 + * @access protected
  78 + * @var int
  79 + */
  80 + var $sessionid = -1;
48 81  
  82 + /**
  83 + * Indicates if the session is active and the user is logged in
  84 + *
  85 + * @access protected
  86 + * @var bool
  87 + */
  88 + var $active;
  89 +
  90 + /**
  91 + * The users id of the user logged in before a new user session was initiated.
  92 + *
  93 + * @access protected
  94 + * @var int
  95 + */
  96 + var $origUserId;
  97 +
  98 + /**
  99 + * Creates a new KTAPI_Session, sets up the internal variables.
  100 + *
  101 + * @author KnowledgeTree Team
  102 + * @access public
  103 + * @param KTAPI $ktapi Instance of the KTAPI object
  104 + * @param User $user Instance of the USER object
  105 + * @return KTAPI_Session
  106 + */
49 107 function KTAPI_Session(&$ktapi, &$user)
50 108 {
51 109 assert(!is_null($ktapi));
... ... @@ -61,9 +119,11 @@ class KTAPI_Session
61 119 }
62 120  
63 121 /**
64   - * return the session string
  122 + * Returns the internal session object
65 123 *
66   - * @return string
  124 + * @author KnowledgeTree Team
  125 + * @access public
  126 + * @return Session
67 127 */
68 128 function get_session()
69 129 {
... ... @@ -73,6 +133,8 @@ class KTAPI_Session
73 133 /**
74 134 * This returns the sessionid in the database.
75 135 *
  136 + * @author KnowledgeTree Team
  137 + * @access public
76 138 * @return int
77 139 */
78 140 function get_sessionid()
... ... @@ -81,8 +143,10 @@ class KTAPI_Session
81 143 }
82 144  
83 145 /**
84   - * Return the user
  146 + * Returns the user object
85 147 *
  148 + * @author KnowledgeTree Team
  149 + * @access public
86 150 * @return User
87 151 */
88 152 function &get_user()
... ... @@ -90,6 +154,12 @@ class KTAPI_Session
90 154 return $this->user;
91 155 }
92 156  
  157 + /**
  158 + * Logs the user out of the session. Sets the session userid back to the original userid
  159 + *
  160 + * @author KnowledgeTree Team
  161 + * @access public
  162 + */
93 163 function logout()
94 164 {
95 165 $_SESSION['userID'] = $this->origUserId;
... ... @@ -97,6 +167,13 @@ class KTAPI_Session
97 167 // don't need to do anything really
98 168 }
99 169  
  170 + /**
  171 + * Checks whether the session is active
  172 + *
  173 + * @author KnowledgeTree Team
  174 + * @access public
  175 + * @return bool TRUE if active | FALSE if not
  176 + */
100 177 function is_active()
101 178 {
102 179 return $this->active;
... ... @@ -104,10 +181,36 @@ class KTAPI_Session
104 181  
105 182 }
106 183  
  184 +/**
  185 + * API for the handling a users session in KnowledgeTree
  186 + *
  187 + * @author KnowledgeTree Team
  188 + * @package KnowledgeTree API
  189 + * @version 0.9
  190 + */
107 191 class KTAPI_UserSession extends KTAPI_Session
108 192 {
  193 +
  194 + /**
  195 + * The users ip address
  196 + *
  197 + * @access protected
  198 + * @var int
  199 + */
109 200 var $ip = null;
110 201  
  202 + /**
  203 + * Create a KTAPI_Session for the current user
  204 + *
  205 + * @author KnowledgeTree Team
  206 + * @access public
  207 + * @param KTAPI $ktapi The KTAPI object
  208 + * @param USER $user The User object
  209 + * @param SESSION $session The current session object
  210 + * @param int $sessionid The id for the current session
  211 + * @param int $ip The users IP address
  212 + * @return KTAPI_UserSession
  213 + */
111 214 function KTAPI_UserSession(&$ktapi, &$user, $session, $sessionid, $ip)
112 215 {
113 216 parent::KTAPI_Session($ktapi, $user);
... ... @@ -125,8 +228,9 @@ class KTAPI_UserSession extends KTAPI_Session
125 228 }
126 229  
127 230 /**
128   - * This resolves the user's ip
  231 + * This resolves the user's ip address
129 232 *
  233 + * @author KnowledgeTree Team
130 234 * @access private
131 235 * @return string
132 236 */
... ... @@ -155,10 +259,15 @@ class KTAPI_UserSession extends KTAPI_Session
155 259 }
156 260  
157 261 /**
  262 + * Checks whether a session exists for the given user and creates a new one or updates the existing one.
158 263 *
  264 + * @author KnowledgeTree Team
159 265 * @access protected
160 266 * @static
161   - * @param User $user
  267 + * @param User $user The User object
  268 + * @param int $ip The users IP address
  269 + * @param string $app The originating application type - ws => webservices | webapp => web application | webdav
  270 + * @return array|PEAR_Error Returns the session string and session id (DB) | a PEAR_Error on failure
162 271 */
163 272 function _check_session(&$user, $ip, $app)
164 273 {
... ... @@ -235,11 +344,15 @@ class KTAPI_UserSession extends KTAPI_Session
235 344 /**
236 345 * This returns a session object based on authentication credentials.
237 346 *
  347 + * @author KnowledgeTree Team
238 348 * @access public
239 349 * @static
240   - * @param string $username
241   - * @param string $password
242   - * @return KTAPI_Session
  350 + * @param KTAPI $ktapi Instance of the KTAPI object
  351 + * @param string $username The users username
  352 + * @param string $password The users password
  353 + * @param string $ip Optional. The users IP address - if null, the method will attempt to resolve it
  354 + * @param string $app Optional. The originating application type - Default is ws => webservices | webapp => The web application
  355 + * @return KTAPI_Session|PEAR_Error Returns the KATPI_UserSession | a PEAR_Error on failure
243 356 */
244 357 function &start_session(&$ktapi, $username, $password, $ip=null, $app='ws')
245 358 {
... ... @@ -277,7 +390,7 @@ class KTAPI_UserSession extends KTAPI_Session
277 390  
278 391 if (PEAR::isError($result))
279 392 {
280   - return $sessionid;
  393 + return $result;
281 394 }
282 395  
283 396 list($session,$sessionid) = $result;
... ... @@ -288,12 +401,15 @@ class KTAPI_UserSession extends KTAPI_Session
288 401 }
289 402  
290 403 /**
291   - * This returns an active session.
  404 + * Returns an active session based on the session string and the ip address if supplied.
292 405 *
293   - * @param KTAPI $ktapi
294   - * @param string $session
295   - * @param string $ip
296   - * @return KTAPI_Session
  406 + * @author KnowledgeTree Team
  407 + * @access public
  408 + * @param KTAPI $ktapi Instance of the KTAPI object
  409 + * @param string $session The session string
  410 + * @param string $ip The users ip address
  411 + * @param string $app Optional. The originating application type - Default is ws => webservices | webapp => The web application
  412 + * @return KTAPI_Session|PEAR_Error Returns the session object | a PEAR_Error on failure
297 413 */
298 414 function &get_active_session(&$ktapi, $session, $ip, $app='ws')
299 415 {
... ... @@ -330,8 +446,11 @@ class KTAPI_UserSession extends KTAPI_Session
330 446 }
331 447  
332 448 /**
333   - * This closes the current session.
  449 + * Ends the current session.
334 450 *
  451 + * @author KnowledgeTree Team
  452 + * @access public
  453 + * @return void|PEAR_Error Returns nothing on success | a PEAR_Error on failure
335 454 */
336 455 function logout()
337 456 {
... ... @@ -350,8 +469,25 @@ class KTAPI_UserSession extends KTAPI_Session
350 469  
351 470 }
352 471  
  472 +/**
  473 + * API for the handling the session for an anonymous user in KnowledgeTree
  474 + *
  475 + * @author KnowledgeTree Team
  476 + * @package KnowledgeTree API
  477 + * @version 0.9
  478 + */
353 479 class KTAPI_AnonymousSession extends KTAPI_UserSession
354 480 {
  481 + /**
  482 + * Creates a session for an anonymous user
  483 + *
  484 + * @author KnowledgeTree Team
  485 + * @access public
  486 + * @param KTAPI $ktapi Instance of the KTAPI object
  487 + * @param string $ip The users ip address
  488 + * @param string $app Optional. The originating application type - Default is ws => webservices | webapp => The web application
  489 + * @return KTAPI_Session|PEAR_Error Returns a session object | a PEAR_Error on failure
  490 + */
355 491 function &start_session(&$ktapi, $ip=null, $app = 'ws')
356 492 {
357 493 $user =& User::get(-2);
... ... @@ -388,8 +524,24 @@ class KTAPI_AnonymousSession extends KTAPI_UserSession
388 524 }
389 525 }
390 526  
  527 +/**
  528 + * API for the handling the system in KnowledgeTree
  529 + *
  530 + * @author KnowledgeTree Team
  531 + * @package KnowledgeTree API
  532 + * @version 0.9
  533 + */
391 534 class KTAPI_SystemSession extends KTAPI_Session
392 535 {
  536 + /**
  537 + * Creates a system session
  538 + *
  539 + * @author KnowledgeTree Team
  540 + * @access public
  541 + * @param KTAPI $ktapi Instance of the KTAPI object
  542 + * @param USER $user Instance of the user object
  543 + * @return KTAPI_SystemSession
  544 + */
393 545 function KTAPI_SystemSession(&$ktapi, &$user)
394 546 {
395 547 parent::KTAPI_Session($ktapi, $user);
... ... @@ -397,4 +549,4 @@ class KTAPI_SystemSession extends KTAPI_Session
397 549 }
398 550 }
399 551  
400 552 -?>
  553 +?>
401 554 \ No newline at end of file
... ...