Session

class Session

Handles all manipulation of the session.

The static methods are used to manipulate the currently active controller's session. The instance methods are used to manipulate a particular session. There can be more than one of these created.

In order to support things like testing, the session is associated with a particular Controller. In normal usage, this is loaded from and saved to the regular PHP session, but for things like static-page-generation and unit-testing, you can create multiple Controllers, each with their own session.

The instance object is basically just a way of manipulating a set of nested maps, and isn't specific to session data.

Saving Data

You can write a value to a users session from your PHP code using the static function {@link Session::set()}. You can add this line in any function or file you wish to save the value.

Session::set('MyValue', 6);

Saves the value of "6" to the MyValue session data. You can also save arrays or serialized objects in session (but note there may be size restrictions as to how much you can save)

// save a variable $var = 1; Session::set('MyVar', $var);

// saves an array
Session::set('MyArrayOfValues', array('1','2','3'));

// saves an object (you'll have to unserialize it back)
$object = new Object();

Session::set('MyObject', serialize($object));

Accessing Data

Once you have saved a value to the Session you can access it by using the {@link Session::get()} function. Like the {@link Session::set()} function you can use this anywhere in your PHP files.

The values in the comments are the values stored from the previous example.

public function bar() { $value = Session::get('MyValue'); // $value = 6 $var = Session::get('MyVar'); // $var = 1 $array = Session::get('MyArrayOfValues'); // $array = array(1,2,3) $object = Session::get('MyObject', unserialize($object)); // $object = Object() }

You can also get all the values in the session at once. This is useful for debugging.

Session::get_all(); // returns an array of all the session values.

Clearing Data

Once you have accessed a value from the Session it doesn't automatically wipe the value from the Session, you have to specifically remove it. To clear a value you can either delete 1 session value by the name that you saved it

Session::clear('MyValue'); // MyValue is no longer 6.

Or you can clear every single value in the session at once. Note SilverStripe stores some of its own session data including form and page comment information. None of this is vital but clear_all will clear everything.

Session::clear_all();

Config options

timeout
session_ips array
cookie_domain string
cookie_path string
session_store_path string
cookie_secure boolean

Methods

__construct($data)

Start PHP session, then create a new Session object with the given start data.

static 
set_cookie_domain(string $domain) deprecated

Cookie domain, for example 'www.php.net'.

static string
get_cookie_domain() deprecated

Get the cookie domain.

static 
set_cookie_path(string $path) deprecated

Path to set on the domain where the session cookie will work.

static string
get_cookie_path() deprecated

Get the path on the domain where the session cookie will work.

static 
set_cookie_secure(boolean $secure) deprecated

Secure cookie, tells the browser to only send it over SSL.

static boolean
get_cookie_secure() deprecated

Get if the cookie is secure

static 
set_session_store_path(string $path) deprecated

Set the session store path

static string
get_session_store_path() deprecated

Get the session store path

static 
set_timeout_ips($ips) deprecated

Provide an array of rules specifing timeouts for IPv4 address ranges or individual IPv4 addresses. The key is an IP address or range and the value is the time until the session expires in seconds. For example:

static 
add_to_array($name, $val)

Add a value to a specific key in the session array

static 
set(string $name, string $val)

Set a key/value pair in the session

static 
get(string $name)

Return a specific value by session key

static Array
get_all()

Return all the values in session

static 
clear(string $name)

Clear a given session key, value pair.

static void
clear_all()

Clear all the values

static 
save()

Save all the values in our session to $_SESSION

inst_start($sid = null)

No description

inst_destroy($removeCookie = true)

No description

inst_set($name, $val)

No description

inst_addToArray($name, $val)

No description

inst_get($name)

No description

inst_clear($name)

No description

inst_clearAll()

No description

inst_getAll()

No description

inst_finalize()

No description

inst_save()

Save data to session Only save the changes, so that anyone manipulating $_SESSION directly doesn't get burned.

array
inst_changedData()

Return the changed data, for debugging purposes.

static 
setFormMessage(string $formname, string $message, string $type)

Sets the appropriate form message in session, with type. This will be shown once, for the form specified.

static bool
request_contains_session_id()

Is there a session ID in the request?

static 
start(string $sid = null)

Initialize session.

static 
destroy(bool $removeCookie = true)

Destroy the active session.

static 
set_timeout(int $timeout) deprecated

Set the timeout of a Session value

static 
get_timeout() deprecated

No description

Details

at line 144
__construct($data)

Start PHP session, then create a new Session object with the given start data.

Parameters

$data array|Session Can be an array of data (such as $_SESSION) or another Session object to clone.

deprecated 4.0 Use the "Session.cookie_domain" config setting instead

Cookie domain, for example 'www.php.net'.

To make cookies visible on all subdomains then the domain must be prefixed with a dot like '.php.net'.

Parameters

string $domain The domain to set

deprecated 4.0 Use the "Session.cookie_domain" config setting instead

Get the cookie domain.

Return Value

string

deprecated 4.0 Use the "Session.cookie_path" config setting instead

Path to set on the domain where the session cookie will work.

Use a single slash ('/') for all paths on the domain.

Parameters

string $path The path to set

deprecated 4.0 Use the "Session.cookie_path" config setting instead

Get the path on the domain where the session cookie will work.

Return Value

string

deprecated 4.0 Use the "Session.cookie_secure" config setting instead

Secure cookie, tells the browser to only send it over SSL.

Parameters

boolean $secure

deprecated 4.0 Use the "Session.cookie_secure" config setting instead

Get if the cookie is secure

Return Value

boolean

at line 238
static set_session_store_path(string $path) deprecated

deprecated 4.0 Use the "Session.session_store_path" config setting instead

Set the session store path

Parameters

string $path Filesystem path to the session store

at line 248
static string get_session_store_path() deprecated

deprecated since version 4.0

Get the session store path

Return Value

string

at line 270
static set_timeout_ips($ips) deprecated

deprecated 4.0 Use the "Session.timeout_ips" config setting instead

Provide an array of rules specifing timeouts for IPv4 address ranges or individual IPv4 addresses. The key is an IP address or range and the value is the time until the session expires in seconds. For example:

Session::set_timeout_ips(array( '127.0.0.1' => 36000 ));

Any user connecting from 127.0.0.1 (localhost) will have their session expired after 10 hours.

Session::set_timeout is used to set the timeout value for any users whose address is not in the given IP range.

Parameters

$ips

at line 278
static add_to_array($name, $val)

Add a value to a specific key in the session array

Parameters

$name
$val

at line 288
static set(string $name, string $val)

Set a key/value pair in the session

Parameters

string $name Key
string $val Value

at line 297
static get(string $name)

Return a specific value by session key

Parameters

string $name Key to lookup

at line 306
static Array get_all()

Return all the values in session

Return Value

Array

at line 315
static clear(string $name)

Clear a given session key, value pair.

Parameters

string $name Key to lookup

at line 324
static void clear_all()

Clear all the values

Return Value

void

at line 332
static save()

Save all the values in our session to $_SESSION

at line 350
inst_start($sid = null)

Parameters

$sid

at line 398
inst_destroy($removeCookie = true)

Parameters

$removeCookie

at line 417
inst_set($name, $val)

Parameters

$name
$val

at line 449
inst_addToArray($name, $val)

Parameters

$name
$val

at line 465
inst_get($name)

Parameters

$name

at line 490
inst_clear($name)

Parameters

$name

at line 514
inst_clearAll()

at line 522
inst_getAll()

at line 526
inst_finalize()

at line 534
inst_save()

Save data to session Only save the changes, so that anyone manipulating $_SESSION directly doesn't get burned.

at line 565
array inst_changedData()

Return the changed data, for debugging purposes.

Return Value

array

at line 577
static setFormMessage(string $formname, string $message, string $type)

Sets the appropriate form message in session, with type. This will be shown once, for the form specified.

Parameters

string $formname the form name you wish to use ( usually $form->FormName() )
string $message the message you wish to add to it
string $type the type of message

at line 586
static bool request_contains_session_id()

Is there a session ID in the request?

Return Value

bool

at line 597
static start(string $sid = null)

Initialize session.

Parameters

string $sid Start the session with a specific ID

at line 606
static destroy(bool $removeCookie = true)

Destroy the active session.

Parameters

bool $removeCookie If set to TRUE, removes the user's cookie, FALSE does not remove

at line 617
static set_timeout(int $timeout) deprecated

deprecated 4.0 Use the "Session.timeout" config setting instead

Set the timeout of a Session value

Parameters

int $timeout Time until a session expires in seconds. Defaults to expire when browser is closed.

at line 625
static get_timeout() deprecated

deprecated 4.0 Use the "Session.timeout" config setting instead