Documentation

CRM_Core_Session
in package

Application

Class CRM_Core_Session.

Constants

USER_CONTEXT = 'userContext'

Properties

$_managedNames : array<string|int, mixed>: Cache of all the session names that we manage.
$_key : string: Key is used to allow the application to have multiple top level scopes rather than a single scope. (avoids naming conflicts). We also extend this idea further and have local scopes within a global scope. Allows us to do cool things like resetting a specific area of the session code while keeping the rest intact
$_session : object: This is just a reference to the real session. Allows us to debug this class a wee bit easier
$_singleton : CRM_Core_Session: We only need one instance of this object. So we use the singleton pattern and cache the instance in this variable

Methods

__construct() : CRM_Core_Session: Constructor.
createScope() : mixed: Creates a session local scope.
debug() : mixed: Dumps the session to the log.
get() : mixed: Gets the value of the named variable in the session scope.
getLoggedInContactDisplayName() : string: Get display name of the logged in user.
getLoggedInContactID() : int|null: Retrieve contact id of the logged in user.
getStatus() : array<string|int, mixed>: Fetches status messages.
getVars() : mixed: Gets all the variables in the current session scope and stuffs them in an associate array.
initialize() : mixed: Creates an array in the session.
isEmpty() : bool: Check if session is empty.
popUserContext() : string: Pops the top userContext stack.
pushUserContext() : mixed: Adds a userContext to the stack.
readUserContext() : string: Reads the top userContext stack.
registerAndRetrieveSessionObjects() : mixed: Register and retrieve session objects.
replaceUserContext() : mixed: Replace the userContext of the stack with the passed one.
reset() : mixed: Resets the session store.
resetScope() : mixed: Resets the session local scope.
set() : mixed: Store a name-value pair in the session scope.
setStatus() : mixed: Stores an alert to be displayed to the user via crm-messages.
singleton() : CRM_Core_Session: Singleton function used to manage this object.
storeSessionObjects() : mixed: Store session objects.
timer() : mixed: Set and check a timer.
useFakeSession() : mixed: Replace the session object with a fake session.

USER_CONTEXT


    public
        mixed
    USER_CONTEXT
    = 'userContext'

$_managedNames

Cache of all the session names that we manage.


    public
    static    array<string|int, mixed>
    $_managedNames
     = \NULL

$_key

Key is used to allow the application to have multiple top level scopes rather than a single scope. (avoids naming conflicts). We also extend this idea further and have local scopes within a global scope. Allows us to do cool things like resetting a specific area of the session code while keeping the rest intact


    protected
        string
    $_key
     = 'CiviCRM'

$_session

This is just a reference to the real session. Allows us to debug this class a wee bit easier


    protected
        object
    $_session
     = \NULL

$_singleton

We only need one instance of this object. So we use the singleton pattern and cache the instance in this variable


    private
    static    CRM_Core_Session
    $_singleton

__construct()

Constructor.


    public
                    __construct() : CRM_Core_Session

The CMS takes care of initiating the php session handler session_start().

All crm code should always use the session using CRM_Core_Session. we prefix stuff to avoid collisions with the CMS and also collisions with other crm modules!

This constructor is invoked whenever any module requests an instance of the session and one is not available.

Return values

CRM_Core_Session

createScope()

Creates a session local scope.


    public
                    createScope(string $prefix[, bool $isRead = FALSE ]) : mixed

Parameters

$prefix : string: Local scope name.
$isRead : bool = FALSE: Is this a read operation, in this case, the session will not be touched.

debug()

Dumps the session to the log.


    public
                    debug([int $all = 1 ]) : mixed

Parameters

$all : int = 1

get()

Gets the value of the named variable in the session scope.


    public
                    get(string $name[, string $prefix = NULL ]) : mixed

This function takes a name and retrieves the value of this variable from the session scope.

Parameters

$name : string: name of the variable.
$prefix : string = NULL: adds another level of scope to the session.

getLoggedInContactDisplayName()

Get display name of the logged in user.


    public
                    getLoggedInContactDisplayName() : string

Return values

string

getLoggedInContactID()

Retrieve contact id of the logged in user.


    public
            static        getLoggedInContactID() : int|null

Return values

int|null —

contact ID of logged in user

getStatus()

Fetches status messages.


    public
                    getStatus([bool $reset = FALSE ]) : array<string|int, mixed>

Parameters

$reset : bool = FALSE: Should we reset the status variable?.

Return values

array<string|int, mixed> —

the status message if any

getVars()

Gets all the variables in the current session scope and stuffs them in an associate array.


    public
                    getVars(array<string|int, mixed> &$vars[, string $prefix = '' ]) : mixed

Parameters

$vars : array<string|int, mixed>: Associative array to store name/value pairs.
$prefix : string = '': Will be stripped from the key before putting it in the return.

initialize()

Creates an array in the session.


    public
                    initialize([bool $isRead = FALSE ]) : mixed

All variables now will be stored under this array.

Parameters

$isRead : bool = FALSE: Is this a read operation, in this case, the session will not be touched.

isEmpty()

Check if session is empty.


    public
                    isEmpty() : bool

if so we don't cache stuff that we can get away with, helps proxies like varnish.

Return values

bool

popUserContext()

Pops the top userContext stack.


    public
                    popUserContext() : string

Return values

string —

the top of the userContext stack (also pops the top element)

pushUserContext()

Adds a userContext to the stack.


    public
                    pushUserContext(string $userContext[, bool $check = TRUE ]) : mixed

Parameters

$userContext : string: The url to return to when done.
$check : bool = TRUE: Should we do a dupe checking with the top element.

readUserContext()

Reads the top userContext stack.


    public
                    readUserContext() : string

Return values

string —

the top of the userContext stack

registerAndRetrieveSessionObjects()


    public
            static        registerAndRetrieveSessionObjects(string|array<string|int, mixed> $names) : mixed

Parameters

$names : string|array<string|int, mixed>

replaceUserContext()

Replace the userContext of the stack with the passed one.


    public
                    replaceUserContext(string $userContext) : mixed

Parameters

$userContext : string: The url to return to when done.

reset()

Resets the session store.


    public
                    reset([int $all = 1 ]) : mixed

Parameters

$all : int = 1

resetScope()

Resets the session local scope.


    public
                    resetScope(string $prefix) : mixed

Parameters

$prefix : string: Local scope name.

set()

Store a name-value pair in the session scope.


    public
                    set(string $name[, mixed $value = NULL ][, string $prefix = NULL ]) : mixed

Parameters

$name : string: Name of the variable.
$value : mixed = NULL: Value of the variable. It is safe to use scalar values here, as well as arrays whose leaf nodes are scalar values. Instances of built-in classes like DateTime may be safe, although the retrieved objects will be copies of the ones saved here. Instances of custom classes (such as those defined in CiviCRM core or extension code) will probably not be rebuilt correctly on retrieval. Resources and other special variable types are not safe to use. References will be dereferenced.
$prefix : string = NULL: A string to prefix the keys in the session with.

setStatus()

Stores an alert to be displayed to the user via crm-messages.


    public
            static        setStatus(string $text[, string $title = '' ][, string $type = 'alert' ][, array<string|int, mixed> $options = [] ]) : mixed

Parameters

$text : string

The status message

$title : string = ''

The optional title of this message

$type : string = 'alert'

The type of this message (printed as a css class). Possible options:

'alert' (default)
'info'
'success'
'error' (this message type by default will remain on the screen until the user dismisses it)
'no-popup' (will display in the document like old-school)

$options : array<string|int, mixed> = []

Additional options. Possible values:

'unique' (default: true) Check if this message was already set before adding
'expires' how long to display this message before fadeout (in ms) set to 0 for no expiration defaults to 10 seconds for most messages, 5 if it has a title but no body, or 0 for errors or messages containing links

singleton()

Singleton function used to manage this object.


    public
            static    &    singleton() : CRM_Core_Session

Return values

CRM_Core_Session

storeSessionObjects()

Store session objects.


    public
            static        storeSessionObjects([bool $reset = TRUE ]) : mixed

Parameters

$reset : bool = TRUE

timer()

Set and check a timer.


    public
                    timer(string $name, int $expire) : mixed

If it's expired, it will be set again.

Good for showing a message to the user every hour or day (so not bugging them on every page) Returns true-ish values if the timer is not set or expired, and false if the timer is still running 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

Parameters

$name : string: name of the timer.
$expire : int: expiry time (in seconds).

useFakeSession()

Replace the session object with a fake session.


    public
            static        useFakeSession() : mixed

CRM_Core_Session in package Application

Table of Contents

Constants

Properties

Methods

Constants

USER_CONTEXT

Properties

$_managedNames

$_key

$_session

$_singleton

Methods

__construct()

Return values

createScope()

Parameters

debug()

Parameters

get()

Parameters

getLoggedInContactDisplayName()

Tags

Return values

getLoggedInContactID()

Return values

getStatus()

Parameters

Return values

getVars()

Parameters

initialize()

Parameters

isEmpty()

Return values

popUserContext()

Return values

pushUserContext()

Parameters

readUserContext()

Return values

registerAndRetrieveSessionObjects()

Parameters

replaceUserContext()

Parameters

reset()

Parameters

resetScope()

Parameters

set()

Parameters

setStatus()

Parameters

singleton()

Return values

storeSessionObjects()

Parameters

timer()

Parameters

useFakeSession()

CRM_Core_Session
in package

Application