modules/uts/uts.session.inc

<?php
// $Id: uts.session.inc,v 1.18 2008/08/05 16:34:27 boombatower Exp $
/**
 * @file
 * Provide Usability Testing Suite session functions.
 *
 * Copyright 2008 by Jimmy Berry ("boombatower", http://drupal.org/user/214218)
 */

/**
 * Generate session id to be used for database and files directory prefix,
 * create Drupal environment, store session record, and create UTS session
 * cookie used to load testing environment.
 *
 * @param integer $study_nid Study NID to create a session for.
 * @return mixed Session ID of created session or FALSE on failure.
 */
function uts_session_create($study_nid) {
  // Generate session id.
  $session_id = 'uts' . mt_rand(1000, 1000000);

  // Generate test environment, both database and files directory.
  $study = node_load($study_nid);
  $copy_prefix = NULL;
  if ($study->base_environment) {
    $copy_prefix = node_load($study->base_environment);
    $copy_prefix = $copy_prefix->prefix;
  }
  if (!uts_environment_invoke_callback('create', $session_id, $copy_prefix)) {
    return FALSE;
  }

  // Load the tasks related to the study and select the first one for the current task.
  $tasks = uts_tasks_load($study_nid);
  db_query("INSERT INTO {uts_session}
            (session_id, study_nid, current_task)
            VALUES ('%s', %d, %d)", $session_id, $study_nid, $tasks[0]->nid);

  // Create session cookie.
  uts_session_set_cookie($session_id);

  return $session_id;
}

/**
 * Restore existing session.
 *
 * @param string $session_id Session ID.
 */
function uts_session_restore($session_id) {
  // Ensure that cookie exits and set it to active.
  uts_session_set_cookie($session_id, TRUE);
}

/**
 * Check for an active user session via cookies.
 *
 * @return Active user session.
 */
function uts_session_active() {
  return isset($_COOKIE['uts_session']) &&
         isset($_COOKIE['uts_session_active']) && $_COOKIE['uts_session_active'];
}

/**
 * Load UTS session data from database.
 *
 * @param string $session_id Session ID.
 * @return object Session object.
 */
function uts_session_load($session_id) {
  $result = db_query("SELECT session_id, study_nid, complete, current_task, start_time
                      FROM {uts_session}
                      WHERE session_id = '%s'", $session_id);
  return db_fetch_object($result);
}

/**
 * Update session task or start time.
 *
 * @param string $session_id The session ID of the session to update.
 * @param interger $task_id The task ID to update session to and set start time to NULL.
 * @param boolean $start Update the start time instead of the task ID.
 */
function uts_session_update($session_id, $task_id = NULL, $start = FALSE) {
  if ($start) {
    db_query("UPDATE {uts_session}
              SET start_time = %d
              WHERE session_id = '%s'", time(), $session_id);
  }
  else {
    db_query("UPDATE {uts_session}
              SET current_task = %d,
              start_time = NULL
              WHERE session_id = '%s'", $task_id, $session_id);
  }
}

/**
 * Mark a session as completed, null the start time, and destroy
 * the test environment.
 *
 * @param string $session_id Session ID to close.
 * @return boolean Success.
 */
function uts_session_close($session_id) {
  db_query("UPDATE {uts_session}
            SET complete = %d,
            start_time = NULL
            WHERE session_id = '%s'", TRUE, $session_id);
  return TRUE;
}

/**
 * Destroy testing environment, remove client cookie, and delete session
 * record from database.
 *
 * @param string $session_id Session to destory.
 * @return boolean Success.
 */
function uts_session_destory($session_id) {
  if (!uts_environment_invoke_callback('destroy', $session_id)) {
    return FALSE;
  }
  uts_session_set_cookie(FALSE);

  // Delete all data stored for session by data collection plug-ins.
  uts_data_delete(NULL, $session_id);

  db_query("DELETE FROM {uts_session_task}
            WHERE session_id = '%s'", $session_id);
  db_query("DELETE FROM {uts_session}
            WHERE session_id = '%s'", $session_id);
  return TRUE;
}

/**
 * Destroy all sessions or sessions related to a specified study NID.
 *
 * @param string $study_nid Study NID of sessions to remove, if NULL then
 *   all sessions will be destroyed.
 * @return boolean Success.
 */
function uts_session_destroy_all($study_nid = NULL) {
  $sessions = uts_session_load_all($study_nid);

  $success = TRUE;
  foreach($sessions as $session_id) {
    if (!uts_session_destory($session_id)) {
      $success = FALSE;
    }
  }
  return $success;
}

/**
 * Load all session IDs.
 *
 * @param string $study_nid Study NID of sessions to remove, if NULL then
 *   all sessions will be destroyed.
 * @param boolean $complete Completion status.
 * @return array List of session IDs.
 */
function uts_session_load_all($study_nid = NULL, $complete = NULL) {
  if ($study_nid) {
    if ($complete !== NULL) {
      $result = db_query('SELECT session_id
                          FROM {uts_session}
                          WHERE study_nid = %d
                          AND complete = %d
                          ORDER BY session_id ASC', $study_nid, $complete);
    }
    else {
      $result = db_query('SELECT session_id
                          FROM {uts_session}
                          WHERE study_nid = %d
                          ORDER BY session_id ASC', $study_nid);
    }
  }
  else {
    if ($complete !== NULL) {
      $result = db_query('SELECT session_id
                        FROM {uts_session}
                        WHERE complete = %d
                        ORDER BY session_id ASC', $complete);
    }
    else {
      $result = db_query('SELECT session_id
                          FROM {uts_session}
                          ORDER BY session_id ASC');
    }
  }

  $sessions = array();
  while ($session_id = db_result($result)) {
    $sessions[] = $session_id;
  }
  return $sessions;
}

/**
 * Set the UTS session cookie.
 *
 * @param string $session_id Session ID.
 * @param boolean $active Session is active.
 */
function uts_session_set_cookie($session_id, $active = FALSE) {
  // Save session for a modest 14 days, afterwhich the session cookie can be
  // re-created. Cookie signifying active session dies when browser is closed.
  setcookie('uts_session', $session_id, time() + 3600 * 24 * 14, '/');
  setcookie('uts_session_active', ($active ? '1' : '0'), 0, '/');
}
1	<?php
2	// $Id: uts.session.inc,v 1.18 2008/08/05 16:34:27 boombatower Exp $
3	/**
4	* @file
5	* Provide Usability Testing Suite session functions.
6	*
7	* Copyright 2008 by Jimmy Berry ("boombatower", http://drupal.org/user/214218)
8	*/
9
10	/**
11	* Generate session id to be used for database and files directory prefix,
12	* create Drupal environment, store session record, and create UTS session
13	* cookie used to load testing environment.
14	*
15	* @param integer $study_nid Study NID to create a session for.
16	* @return mixed Session ID of created session or FALSE on failure.
17	*/
18	function uts_session_create($study_nid) {
19	// Generate session id.
20	$session_id = 'uts' . mt_rand(1000, 1000000);
21
22	// Generate test environment, both database and files directory.
23	$study = node_load($study_nid);
24	$copy_prefix = NULL;
25	if ($study->base_environment) {
26	$copy_prefix = node_load($study->base_environment);
27	$copy_prefix = $copy_prefix->prefix;
28	}
29	if (!uts_environment_invoke_callback('create', $session_id, $copy_prefix)) {
30	return FALSE;
31	}
32
33	// Load the tasks related to the study and select the first one for the current task.
34	$tasks = uts_tasks_load($study_nid);
35	db_query("INSERT INTO {uts_session}
36	(session_id, study_nid, current_task)
37	VALUES ('%s', %d, %d)", $session_id, $study_nid, $tasks[0]->nid);
38
39	// Create session cookie.
40	uts_session_set_cookie($session_id);
41
42	return $session_id;
43	}
44
45	/**
46	* Restore existing session.
47	*
48	* @param string $session_id Session ID.
49	*/
50	function uts_session_restore($session_id) {
51	// Ensure that cookie exits and set it to active.
52	uts_session_set_cookie($session_id, TRUE);
53	}
54
55	/**
56	* Check for an active user session via cookies.
57	*
58	* @return Active user session.
59	*/
60	function uts_session_active() {
61	return isset($_COOKIE['uts_session']) &&
62	isset($_COOKIE['uts_session_active']) && $_COOKIE['uts_session_active'];
63	}
64
65	/**
66	* Load UTS session data from database.
67	*
68	* @param string $session_id Session ID.
69	* @return object Session object.
70	*/
71	function uts_session_load($session_id) {
72	$result = db_query("SELECT session_id, study_nid, complete, current_task, start_time
73	FROM {uts_session}
74	WHERE session_id = '%s'", $session_id);
75	return db_fetch_object($result);
76	}
77
78	/**
79	* Update session task or start time.
80	*
81	* @param string $session_id The session ID of the session to update.
82	* @param interger $task_id The task ID to update session to and set start time to NULL.
83	* @param boolean $start Update the start time instead of the task ID.
84	*/
85	function uts_session_update($session_id, $task_id = NULL, $start = FALSE) {
86	if ($start) {
87	db_query("UPDATE {uts_session}
88	SET start_time = %d
89	WHERE session_id = '%s'", time(), $session_id);
90	}
91	else {
92	db_query("UPDATE {uts_session}
93	SET current_task = %d,
94	start_time = NULL
95	WHERE session_id = '%s'", $task_id, $session_id);
96	}
97	}
98
99	/**
100	* Mark a session as completed, null the start time, and destroy
101	* the test environment.
102	*
103	* @param string $session_id Session ID to close.
104	* @return boolean Success.
105	*/
106	function uts_session_close($session_id) {
107	db_query("UPDATE {uts_session}
108	SET complete = %d,
109	start_time = NULL
110	WHERE session_id = '%s'", TRUE, $session_id);
111	return TRUE;
112	}
113
114	/**
115	* Destroy testing environment, remove client cookie, and delete session
116	* record from database.
117	*
118	* @param string $session_id Session to destory.
119	* @return boolean Success.
120	*/
121	function uts_session_destory($session_id) {
122	if (!uts_environment_invoke_callback('destroy', $session_id)) {
123	return FALSE;
124	}
125	uts_session_set_cookie(FALSE);
126
127	// Delete all data stored for session by data collection plug-ins.
128	uts_data_delete(NULL, $session_id);
129
130	db_query("DELETE FROM {uts_session_task}
131	WHERE session_id = '%s'", $session_id);
132	db_query("DELETE FROM {uts_session}
133	WHERE session_id = '%s'", $session_id);
134	return TRUE;
135	}
136
137	/**
138	* Destroy all sessions or sessions related to a specified study NID.
139	*
140	* @param string $study_nid Study NID of sessions to remove, if NULL then
141	* all sessions will be destroyed.
142	* @return boolean Success.
143	*/
144	function uts_session_destroy_all($study_nid = NULL) {
145	$sessions = uts_session_load_all($study_nid);
146
147	$success = TRUE;
148	foreach($sessions as $session_id) {
149	if (!uts_session_destory($session_id)) {
150	$success = FALSE;
151	}
152	}
153	return $success;
154	}
155
156	/**
157	* Load all session IDs.
158	*
159	* @param string $study_nid Study NID of sessions to remove, if NULL then
160	* all sessions will be destroyed.
161	* @param boolean $complete Completion status.
162	* @return array List of session IDs.
163	*/
164	function uts_session_load_all($study_nid = NULL, $complete = NULL) {
165	if ($study_nid) {
166	if ($complete !== NULL) {
167	$result = db_query('SELECT session_id
168	FROM {uts_session}
169	WHERE study_nid = %d
170	AND complete = %d
171	ORDER BY session_id ASC', $study_nid, $complete);
172	}
173	else {
174	$result = db_query('SELECT session_id
175	FROM {uts_session}
176	WHERE study_nid = %d
177	ORDER BY session_id ASC', $study_nid);
178	}
179	}
180	else {
181	if ($complete !== NULL) {
182	$result = db_query('SELECT session_id
183	FROM {uts_session}
184	WHERE complete = %d
185	ORDER BY session_id ASC', $complete);
186	}
187	else {
188	$result = db_query('SELECT session_id
189	FROM {uts_session}
190	ORDER BY session_id ASC');
191	}
192	}
193
194	$sessions = array();
195	while ($session_id = db_result($result)) {
196	$sessions[] = $session_id;
197	}
198	return $sessions;
199	}
200
201	/**
202	* Set the UTS session cookie.
203	*
204	* @param string $session_id Session ID.
205	* @param boolean $active Session is active.
206	*/
207	function uts_session_set_cookie($session_id, $active = FALSE) {
208	// Save session for a modest 14 days, afterwhich the session cookie can be
209	// re-created. Cookie signifying active session dies when browser is closed.
210	setcookie('uts_session', $session_id, time() + 3600 * 24 * 14, '/');
211	setcookie('uts_session_active', ($active ? '1' : '0'), 0, '/');
212	}