3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.4 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2013 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
29 require_once "PEAR.php";
30 class CRM_Core_Session
{
33 * Cache of all the session names that we manage
35 static $_managedNames = NULL;
38 * key is used to allow the application to have multiple top
39 * level scopes rather than a single scope. (avoids naming
40 * conflicts). We also extend this idea further and have local
41 * scopes within a global scope. Allows us to do cool things
42 * like resetting a specific area of the session code while
43 * keeping the rest intact
47 protected $_key = 'CiviCRM';
48 CONST USER_CONTEXT
= 'userContext';
51 * This is just a reference to the real session. Allows us to
52 * debug this class a wee bit easier
56 protected $_session = NULL;
59 * We only need one instance of this object. So we use the singleton
60 * pattern and cache the instance in this variable
65 static private $_singleton = NULL;
70 * Since we are now a client / module of drupal, drupal takes care
71 * of initiating the php session handler session_start ().
73 * When using CiviCRM standalone (i.e. w/o Drupal), we start the session
74 * in index.php and then pass it off to here.
76 * All crm code should always use the session using
77 * CRM_Core_Session. we prefix stuff to avoid collisions with drupal and also
78 * collisions with other crm modules!!
79 * This constructor is invoked whenever any module requests an instance of
80 * the session and one is not available.
84 function __construct() {
85 $this->_session
= null;
89 * singleton function used to manage this object
91 * @return CRM_Core_Session
94 static function &singleton() {
95 if (self
::$_singleton === NULL) {
96 self
::$_singleton = new CRM_Core_Session
;
98 return self
::$_singleton;
102 * Creates an array in the session. All variables now will be stored
105 * @param boolean isRead is this a read operation, in this case, the session will not be touched
111 function initialize($isRead = FALSE) {
112 // lets initialize the _session variable just before we need it
113 // hopefully any bootstrapping code will actually load the session from the CMS
114 if (!isset($this->_session
)) {
116 if (!isset($_SESSION) && PHP_SAPI
!== 'cli') {
120 $config =& CRM_Core_Config
::singleton();
121 if ($config->userSystem
->is_drupal
&& function_exists('drupal_session_start')) {
122 drupal_session_start();
128 $this->_session
=& $_SESSION;
135 if (!isset($this->_session
[$this->_key
]) ||
136 !is_array($this->_session
[$this->_key
])
138 $this->_session
[$this->_key
] = array();
144 * Resets the session store
150 function reset($all = 1) {
154 // to make certain we clear it, first initialize it to empty
155 $this->_session
[$this->_key
] = array();
156 unset($this->_session
[$this->_key
]);
159 $this->_session
= array();
166 * creates a session local scope
168 * @param string prefix local scope name
169 * @param boolean isRead is this a read operation, in this case, the session will not be touched
175 function createScope($prefix, $isRead = FALSE) {
176 $this->initialize($isRead);
178 if ($isRead ||
empty($prefix)) {
182 if (!CRM_Utils_Array
::value($prefix, $this->_session
[$this->_key
])) {
183 $this->_session
[$this->_key
][$prefix] = array();
188 * resets the session local scope
190 * @param string local scope name
195 function resetScope($prefix) {
198 if (empty($prefix)) {
202 if (array_key_exists($prefix, $this->_session
[$this->_key
])) {
203 unset($this->_session
[$this->_key
][$prefix]);
208 * Store the variable with the value in the session scope
210 * This function takes a name, value pair and stores this
211 * in the session scope. Not sure what happens if we try
212 * to store complex objects in the session. I suspect it
213 * is supported but we need to verify this
217 * @param string $name name of the variable
218 * @param mixed $value value of the variable
219 * @param string $prefix a string to prefix the keys in the session with
224 function set($name, $value = NULL, $prefix = NULL) {
225 // create session scope
226 $this->createScope($prefix);
228 if (empty($prefix)) {
229 $session = &$this->_session
[$this->_key
];
232 $session = &$this->_session
[$this->_key
][$prefix];
235 if (is_array($name)) {
236 foreach ($name as $n => $v) {
241 $session[$name] = $value;
246 * Gets the value of the named variable in the session scope
248 * This function takes a name and retrieves the value of this
249 * variable from the session scope.
253 * @param string name : name of the variable
254 * @param string prefix : adds another level of scope to the session
259 function get($name, $prefix = NULL) {
260 // create session scope
261 $this->createScope($prefix, TRUE);
263 if (empty($this->_session
) ||
empty($this->_session
[$this->_key
])) {
267 if (empty($prefix)) {
268 $session =& $this->_session
[$this->_key
];
271 if (empty($this->_session
[$this->_key
][$prefix])) {
274 $session =& $this->_session
[$this->_key
][$prefix];
277 return CRM_Utils_Array
::value($name, $session);
281 * Gets all the variables in the current session scope
282 * and stuffs them in an associate array
286 * @param array vars : associative array to store name/value pairs
287 * @param string Strip prefix from the key before putting it in the return
292 function getVars(&$vars, $prefix = '') {
293 // create session scope
294 $this->createScope($prefix, TRUE);
296 if (empty($prefix)) {
297 $values = &$this->_session
[$this->_key
];
300 $values = CRM_Core_BAO_Cache
::getItem('CiviCRM Session', "CiviCRM_{$prefix}");
304 foreach ($values as $name => $value) {
305 $vars[$name] = $value;
311 * Set and check a timer. If it's expired, it will be set again.
312 * Good for showing a message to the user every hour or day (so not bugging them on every page)
313 * Returns true-ish values if the timer is not set or expired, and false if the timer is still running
314 * If you want to get more nuanced, you can check the type of the return to see if it's 'not set' or actually expired at a certain time
318 * @param string name : name of the timer
319 * @param int expire : expiry time (in seconds)
324 function timer($name, $expire) {
325 $ts = $this->get($name, 'timer');
326 if (!$ts ||
$ts < time() - $expire) {
327 $this->set($name, time(), 'timer');
328 return $ts ?
$ts : 'not set';
334 * adds a userContext to the stack
336 * @param string $userContext the url to return to when done
337 * @param boolean $check should we do a dupe checking with the top element
344 function pushUserContext($userContext, $check = TRUE) {
345 if (empty($userContext)) {
349 $this->createScope(self
::USER_CONTEXT
);
351 // hack, reset if too big
352 if (count($this->_session
[$this->_key
][self
::USER_CONTEXT
]) > 10) {
353 $this->resetScope(self
::USER_CONTEXT
);
354 $this->createScope(self
::USER_CONTEXT
);
357 $topUC = array_pop($this->_session
[$this->_key
][self
::USER_CONTEXT
]);
359 // see if there is a match between the new UC and the top one. the match needs to be
360 // fuzzy since we use the referer at times
361 // if close enough, lets just replace the top with the new one
362 if ($check && $topUC && CRM_Utils_String
::match($topUC, $userContext)) {
363 array_push($this->_session
[$this->_key
][self
::USER_CONTEXT
], $userContext);
367 array_push($this->_session
[$this->_key
][self
::USER_CONTEXT
], $topUC);
369 array_push($this->_session
[$this->_key
][self
::USER_CONTEXT
], $userContext);
374 * replace the userContext of the stack with the passed one
376 * @param string the url to return to when done
383 function replaceUserContext($userContext) {
384 if (empty($userContext)) {
388 $this->createScope(self
::USER_CONTEXT
);
390 array_pop($this->_session
[$this->_key
][self
::USER_CONTEXT
]);
391 array_push($this->_session
[$this->_key
][self
::USER_CONTEXT
], $userContext);
395 * pops the top userContext stack
399 * @return the top of the userContext stack (also pops the top element)
402 function popUserContext() {
403 $this->createScope(self
::USER_CONTEXT
);
405 return array_pop($this->_session
[$this->_key
][self
::USER_CONTEXT
]);
409 * reads the top userContext stack
413 * @return the top of the userContext stack
416 function readUserContext() {
417 $this->createScope(self
::USER_CONTEXT
);
419 $config = CRM_Core_Config
::singleton();
420 $lastElement = count($this->_session
[$this->_key
][self
::USER_CONTEXT
]) - 1;
421 return $lastElement >= 0 ?
$this->_session
[$this->_key
][self
::USER_CONTEXT
][$lastElement] : $config->userFrameworkBaseURL
;
425 * dumps the session to the log
427 function debug($all = 1) {
430 CRM_Core_Error
::debug('CRM Session', $this->_session
);
433 CRM_Core_Error
::debug('CRM Session', $this->_session
[$this->_key
]);
438 * Fetches status messages
440 * @param $reset boolean should we reset the status variable?
442 * @return string the status message if any
444 function getStatus($reset = FALSE) {
448 if (array_key_exists('status', $this->_session
[$this->_key
])) {
449 $status = $this->_session
[$this->_key
]['status'];
452 $this->_session
[$this->_key
]['status'] = NULL;
453 unset($this->_session
[$this->_key
]['status']);
459 * Stores an alert to be displayed to the user via crm-messages
461 * @param $text string
464 * @param $title string
465 * The optional title of this message
467 * @param $type string
468 * The type of this message (printed as a css class). Possible options:
469 * - 'alert' (default)
472 * - 'error' (this message type by default will remain on the screen
473 * until the user dismisses it)
474 * - 'no-popup' (will display in the document like old-school)
476 * @param $options array
477 * Additional options. Possible values:
478 * - 'unique' (default: true) Check if this message was already set before adding
479 * - 'expires' how long to display this message before fadeout (in ms)
480 * set to 0 for no expiration
481 * defaults to 10 seconds for most messages, 5 if it has a title but no body,
482 * or 0 for errors or messages containing links
488 static function setStatus($text, $title = '', $type = 'alert', $options = array()) {
489 // make sure session is initialized, CRM-8120
490 $session = self
::singleton();
491 $session->initialize();
494 $options +
= array('unique' => TRUE);
496 if (!isset(self
::$_singleton->_session
[self
::$_singleton->_key
]['status'])) {
497 self
::$_singleton->_session
[self
::$_singleton->_key
]['status'] = array();
500 if ($options['unique']) {
501 foreach (self
::$_singleton->_session
[self
::$_singleton->_key
]['status'] as $msg) {
502 if ($msg['text'] == $text && $msg['title'] == $title) {
507 unset($options['unique']);
508 self
::$_singleton->_session
[self
::$_singleton->_key
]['status'][] = array(
512 'options' => $options ?
json_encode($options) : NULL,
517 static function registerAndRetrieveSessionObjects($names) {
518 if (!is_array($names)) {
519 $names = array($names);
522 if (!self
::$_managedNames) {
523 self
::$_managedNames = $names;
526 self
::$_managedNames = array_merge(self
::$_managedNames, $names);
529 CRM_Core_BAO_Cache
::restoreSessionFromCache($names);
532 static function storeSessionObjects($reset = TRUE) {
533 if (empty(self
::$_managedNames)) {
537 self
::$_managedNames = CRM_Utils_Array
::crmArrayUnique(self
::$_managedNames);
539 CRM_Core_BAO_Cache
::storeSessionToCache(self
::$_managedNames, $reset);
541 self
::$_managedNames = NULL;
545 // check if session is empty, if so we dont cache
546 // stuff that we can get away with
547 // helps proxies like varnish
548 return empty($_SESSION) ?
TRUE : FALSE;