3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
13 * Class CRM_Core_Session.
15 class CRM_Core_Session
{
18 * Cache of all the session names that we manage.
21 public static $_managedNames = NULL;
24 * Key is used to allow the application to have multiple top
25 * level scopes rather than a single scope. (avoids naming
26 * conflicts). We also extend this idea further and have local
27 * scopes within a global scope. Allows us to do cool things
28 * like resetting a specific area of the session code while
29 * keeping the rest intact
33 protected $_key = 'CiviCRM';
34 const USER_CONTEXT
= 'userContext';
37 * This is just a reference to the real session. Allows us to
38 * debug this class a wee bit easier
42 protected $_session = NULL;
45 * We only need one instance of this object. So we use the singleton
46 * pattern and cache the instance in this variable
50 static private $_singleton = NULL;
55 * The CMS takes care of initiating the php session handler session_start().
57 * All crm code should always use the session using
58 * CRM_Core_Session. we prefix stuff to avoid collisions with the CMS and also
59 * collisions with other crm modules!
61 * This constructor is invoked whenever any module requests an instance of
62 * the session and one is not available.
64 * @return CRM_Core_Session
66 public function __construct() {
67 $this->_session
= NULL;
71 * Singleton function used to manage this object.
73 * @return CRM_Core_Session
75 public static function &singleton() {
76 if (self
::$_singleton === NULL) {
77 self
::$_singleton = new CRM_Core_Session();
79 return self
::$_singleton;
83 * Creates an array in the session.
85 * All variables now will be stored under this array.
88 * Is this a read operation, in this case, the session will not be touched.
90 public function initialize($isRead = FALSE) {
91 // lets initialize the _session variable just before we need it
92 // hopefully any bootstrapping code will actually load the session from the CMS
93 if (!isset($this->_session
)) {
95 if (!isset($_SESSION) && PHP_SAPI
!== 'cli') {
99 // FIXME: This belongs in CRM_Utils_System_*
100 if (CRM_Core_Config
::singleton()->userSystem
->is_drupal
&& function_exists('drupal_session_start')) {
101 // https://issues.civicrm.org/jira/browse/CRM-14356
102 if (!(isset($GLOBALS['lazy_session']) && $GLOBALS['lazy_session'] == TRUE)) {
103 drupal_session_start();
111 $this->_session
=& $_SESSION;
118 if (!isset($this->_session
[$this->_key
]) ||
119 !is_array($this->_session
[$this->_key
])
121 $this->_session
[$this->_key
] = [];
126 * Resets the session store.
130 public function reset($all = 1) {
134 // to make certain we clear it, first initialize it to empty
135 $this->_session
[$this->_key
] = [];
136 unset($this->_session
[$this->_key
]);
139 $this->_session
= [];
145 * Creates a session local scope.
147 * @param string $prefix
149 * @param bool $isRead
150 * Is this a read operation, in this case, the session will not be touched.
152 public function createScope($prefix, $isRead = FALSE) {
153 $this->initialize($isRead);
155 if ($isRead ||
empty($prefix)) {
159 if (empty($this->_session
[$this->_key
][$prefix])) {
160 $this->_session
[$this->_key
][$prefix] = [];
165 * Resets the session local scope.
167 * @param string $prefix
170 public function resetScope($prefix) {
173 if (empty($prefix)) {
177 if (array_key_exists($prefix, $this->_session
[$this->_key
])) {
178 unset($this->_session
[$this->_key
][$prefix]);
183 * Store the variable with the value in the session scope.
185 * This function takes a name, value pair and stores this
186 * in the session scope. Not sure what happens if we try
187 * to store complex objects in the session. I suspect it
188 * is supported but we need to verify this
191 * @param string $name
192 * Name of the variable.
193 * @param mixed $value
194 * Value of the variable.
195 * @param string $prefix
196 * A string to prefix the keys in the session with.
198 public function set($name, $value = NULL, $prefix = NULL) {
199 // create session scope
200 $this->createScope($prefix);
202 if (empty($prefix)) {
203 $session = &$this->_session
[$this->_key
];
206 $session = &$this->_session
[$this->_key
][$prefix];
209 if (is_array($name)) {
210 foreach ($name as $n => $v) {
215 $session[$name] = $value;
220 * Gets the value of the named variable in the session scope.
222 * This function takes a name and retrieves the value of this
223 * variable from the session scope.
226 * @param string $name
227 * name of the variable.
228 * @param string $prefix
229 * adds another level of scope to the session.
233 public function get($name, $prefix = NULL) {
234 // create session scope
235 $this->createScope($prefix, TRUE);
237 if (empty($this->_session
) ||
empty($this->_session
[$this->_key
])) {
241 if (empty($prefix)) {
242 $session =& $this->_session
[$this->_key
];
245 if (empty($this->_session
[$this->_key
][$prefix])) {
248 $session =& $this->_session
[$this->_key
][$prefix];
251 return CRM_Utils_Array
::value($name, $session);
255 * Gets all the variables in the current session scope and stuffs them in an associate array.
258 * Associative array to store name/value pairs.
259 * @param string $prefix
260 * Will be stripped from the key before putting it in the return.
262 public function getVars(&$vars, $prefix = '') {
263 // create session scope
264 $this->createScope($prefix, TRUE);
266 if (empty($prefix)) {
267 $values = &$this->_session
[$this->_key
];
270 $values = Civi
::cache('session')->get("CiviCRM_{$prefix}");
274 foreach ($values as $name => $value) {
275 $vars[$name] = $value;
281 * Set and check a timer.
283 * If it's expired, it will be set again.
285 * Good for showing a message to the user every hour or day (so not bugging them on every page)
286 * Returns true-ish values if the timer is not set or expired, and false if the timer is still running
287 * 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
290 * @param string $name
293 * expiry time (in seconds).
297 public function timer($name, $expire) {
298 $ts = $this->get($name, 'timer');
299 if (!$ts ||
$ts < time() - $expire) {
300 $this->set($name, time(), 'timer');
301 return $ts ?
$ts : 'not set';
307 * Adds a userContext to the stack.
309 * @param string $userContext
310 * The url to return to when done.
312 * Should we do a dupe checking with the top element.
314 public function pushUserContext($userContext, $check = TRUE) {
315 if (empty($userContext)) {
319 $this->createScope(self
::USER_CONTEXT
);
321 // hack, reset if too big
322 if (count($this->_session
[$this->_key
][self
::USER_CONTEXT
]) > 10) {
323 $this->resetScope(self
::USER_CONTEXT
);
324 $this->createScope(self
::USER_CONTEXT
);
327 $topUC = array_pop($this->_session
[$this->_key
][self
::USER_CONTEXT
]);
329 // see if there is a match between the new UC and the top one. the match needs to be
330 // fuzzy since we use the referer at times
331 // if close enough, lets just replace the top with the new one
332 if ($check && $topUC && CRM_Utils_String
::match($topUC, $userContext)) {
333 array_push($this->_session
[$this->_key
][self
::USER_CONTEXT
], $userContext);
337 array_push($this->_session
[$this->_key
][self
::USER_CONTEXT
], $topUC);
339 array_push($this->_session
[$this->_key
][self
::USER_CONTEXT
], $userContext);
344 * Replace the userContext of the stack with the passed one.
346 * @param string $userContext
347 * The url to return to when done.
349 public function replaceUserContext($userContext) {
350 if (empty($userContext)) {
354 $this->createScope(self
::USER_CONTEXT
);
356 array_pop($this->_session
[$this->_key
][self
::USER_CONTEXT
]);
357 array_push($this->_session
[$this->_key
][self
::USER_CONTEXT
], $userContext);
361 * Pops the top userContext stack.
364 * the top of the userContext stack (also pops the top element)
366 public function popUserContext() {
367 $this->createScope(self
::USER_CONTEXT
);
369 return array_pop($this->_session
[$this->_key
][self
::USER_CONTEXT
]);
373 * Reads the top userContext stack.
376 * the top of the userContext stack
378 public function readUserContext() {
379 $this->createScope(self
::USER_CONTEXT
);
381 $config = CRM_Core_Config
::singleton();
382 $lastElement = count($this->_session
[$this->_key
][self
::USER_CONTEXT
]) - 1;
383 return $lastElement >= 0 ?
$this->_session
[$this->_key
][self
::USER_CONTEXT
][$lastElement] : $config->userFrameworkBaseURL
;
387 * Dumps the session to the log.
391 public function debug($all = 1) {
394 CRM_Core_Error
::debug('CRM Session', $this->_session
);
397 CRM_Core_Error
::debug('CRM Session', $this->_session
[$this->_key
]);
402 * Fetches status messages.
405 * Should we reset the status variable?.
408 * the status message if any
410 public function getStatus($reset = FALSE) {
414 if (array_key_exists('status', $this->_session
[$this->_key
])) {
415 $status = $this->_session
[$this->_key
]['status'];
418 $this->_session
[$this->_key
]['status'] = NULL;
419 unset($this->_session
[$this->_key
]['status']);
425 * Stores an alert to be displayed to the user via crm-messages.
427 * @param string $text
430 * @param string $title
431 * The optional title of this message
433 * @param string $type
434 * The type of this message (printed as a css class). Possible options:
435 * - 'alert' (default)
438 * - 'error' (this message type by default will remain on the screen
439 * until the user dismisses it)
440 * - 'no-popup' (will display in the document like old-school)
442 * @param array $options
443 * Additional options. Possible values:
444 * - 'unique' (default: true) Check if this message was already set before adding
445 * - 'expires' how long to display this message before fadeout (in ms)
446 * set to 0 for no expiration
447 * defaults to 10 seconds for most messages, 5 if it has a title but no body,
448 * or 0 for errors or messages containing links
450 public static function setStatus($text, $title = '', $type = 'alert', $options = []) {
451 // make sure session is initialized, CRM-8120
452 $session = self
::singleton();
453 $session->initialize();
455 // Sanitize any HTML we're displaying. This helps prevent reflected XSS in error messages.
456 $text = CRM_Utils_String
::purifyHTML($text);
457 $title = CRM_Utils_String
::purifyHTML($title);
460 $options +
= ['unique' => TRUE];
462 if (!isset(self
::$_singleton->_session
[self
::$_singleton->_key
]['status'])) {
463 self
::$_singleton->_session
[self
::$_singleton->_key
]['status'] = [];
465 if ($text ||
$title) {
466 if ($options['unique']) {
467 foreach (self
::$_singleton->_session
[self
::$_singleton->_key
]['status'] as $msg) {
468 if ($msg['text'] == $text && $msg['title'] == $title) {
473 unset($options['unique']);
474 self
::$_singleton->_session
[self
::$_singleton->_key
]['status'][] = [
478 'options' => $options ?
$options : NULL,
484 * Register and retrieve session objects.
486 * @param string|array $names
488 public static function registerAndRetrieveSessionObjects($names) {
489 if (!is_array($names)) {
493 if (!self
::$_managedNames) {
494 self
::$_managedNames = $names;
497 self
::$_managedNames = array_merge(self
::$_managedNames, $names);
500 CRM_Core_BAO_Cache
::restoreSessionFromCache($names);
504 * Store session objects.
508 public static function storeSessionObjects($reset = TRUE) {
509 if (empty(self
::$_managedNames)) {
513 self
::$_managedNames = CRM_Utils_Array
::crmArrayUnique(self
::$_managedNames);
515 CRM_Core_BAO_Cache
::storeSessionToCache(self
::$_managedNames, $reset);
517 self
::$_managedNames = NULL;
521 * Retrieve contact id of the logged in user.
524 * contact ID of logged in user
526 public static function getLoggedInContactID() {
527 $session = CRM_Core_Session
::singleton();
528 if (!is_numeric($session->get('userID'))) {
531 return $session->get('userID');
535 * Get display name of the logged in user.
539 * @throws CiviCRM_API3_Exception
541 public function getLoggedInContactDisplayName() {
542 $userContactID = CRM_Core_Session
::getLoggedInContactID();
543 if (!$userContactID) {
546 return civicrm_api3('Contact', 'getvalue', ['id' => $userContactID, 'return' => 'display_name']);
550 * Check if session is empty.
552 * if so we don't cache stuff that we can get away with, helps proxies like varnish.
556 public function isEmpty() {
557 return empty($_SESSION);