Version: current

# 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 `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 `Session::get()` function. Like the `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.

    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::getAll(); // 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::clearAll();

Package: sapphire\control
See: ``Cookie``
Located at sapphire/core/Session.php

## Methods summary

`public static` | # `set_cookie_domain( string $domain )` Cookie domain, for example 'www.php.net'. 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 $domain string $domain The domain to set
`public static string` | # `get_cookie_domain( )` Get the cookie domain. Get the cookie domain. #### Returns `string` string
`public static` | # `set_cookie_path( string $path )` Path to set on the domain where the session cookie will work. Use a single slash ('/') for all paths on the domain. Path to set on the domain where the session cookie will work. Use a single slash ('/') for all paths on the domain. #### Parameters $path string $path The path to set
`public static string` | # `get_cookie_path( )` Get the path on the domain where the session cookie will work. Get the path on the domain where the session cookie will work. #### Returns `string` string
`public static` | # `set_cookie_secure( boolean $secure )` Secure cookie, tells the browser to only send it over SSL. Secure cookie, tells the browser to only send it over SSL. #### Parameters $secure boolean $secure
`public static boolean` | # `get_cookie_secure( )` Get if the cookie is secure Get if the cookie is secure #### Returns `boolean` boolean
`public` | # `__construct( mixed $data )` Create a new session object, with the given starting data Create a new session object, with the given starting data #### Parameters $data $data Can be an array of data (such as $_SESSION) or another Session object to clone.
`public static` | # `set_timeout_ips( array $session_ips )` 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: 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 $session_ips array $session_ips Array of IPv4 rules.
`public static` | # `addToArray( mixed $name, mixed $val )` #### Deprecated 2.5 Use Session::add_to_array($name, $val) instead
`public static` | # `add_to_array( mixed $name, mixed $val )` Add a value to a specific key in the session array Add a value to a specific key in the session array
`public static` | # `set( string $name, string $val )` Set a key/value pair in the session Set a key/value pair in the session #### Parameters $name string $name Key $val string $val Value
`public static` | # `get( string $name )` Return a specific value by session key Return a specific value by session key #### Parameters $name string $name Key to lookup
`public static Array` | # `get_all( )` Return all the values in session Return all the values in session #### Returns `Array` Array
`public static` | # `getAll( )` #### Deprecated 2.5 Use Session::get_all()
`public static` | # `clear( string $name )` Clear a given session key, value pair. Clear a given session key, value pair. #### Parameters $name string $name Key to lookup
`public static` | # `clear_all( )` Clear all the values Clear all the values
`public static` | # `clearAll( )` #### Deprecated 2.5 Use Session::clear_all()
`public static` | # `save( )` Save all the values in our session to $_SESSION Save all the values in our session to $_SESSION
`protected static` | # `current_session( )`
`public` | # `inst_set( mixed $name, mixed $val )`
`public` | # `inst_addToArray( mixed $name, mixed $val )`
`public` | # `inst_get( mixed $name )`
`public` | # `inst_clear( mixed $name )`
`public` | # `inst_clearAll( )`
`public` | # `inst_getAll( )`
`public` | # `inst_save( )` Save data to session Only save the changes, so that anyone manipulating $_SESSION directly doesn't get burned. Save data to session Only save the changes, so that anyone manipulating $_SESSION directly doesn't get burned.
`protected` | # `recursivelyApply( mixed $data, mixed & $dest )` Recursively apply the changes represented in $data to $dest. Used to update $_SESSION Recursively apply the changes represented in $data to $dest. Used to update $_SESSION
`public static` | # `setFormMessage( formname $formname, messsage $message, type $type )` Sets the appropriate form message in session, with type. This will be shown once, for the form specified. Sets the appropriate form message in session, with type. This will be shown once, for the form specified. #### Parameters $formname formname the form name you wish to use ( usually $form->FormName() ) $message messsage the message you wish to add to it $type type the type of message
`public static` | # `start( string $sid = null )` Initialize session. Initialize session. #### Parameters $sid string $sid Start the session with a specific ID
`public static` | # `destroy( boolean $removeCookie = true )` Destroy the active session. Destroy the active session. #### Parameters $removeCookie bool $removeCookie If set to TRUE, removes the user's cookie, FALSE does not remove
`public static` | # `load_config( )` Use the Session::$session_ips array to set timeouts based on IP address or IP address range. Use the Session::$session_ips array to set timeouts based on IP address or IP address range. Note: The use of _sessions.php is deprecated.
`public static` | # `set_timeout( integer $timeout )` Set the timeout of a Session value Set the timeout of a Session value #### Parameters $timeout int $timeout Time until a session expires in seconds. Defaults to expire when browser is closed.
`public static` | # `get_timeout( )`

### Magic methods summary

## Properties summary

`protected static integer` | $timeout | # Set session timeout Set session timeout
`protected static array` | $session_ips | #
`protected static mixed` | $cookie_domain | #
`protected static mixed` | $cookie_path | #
`protected static boolean` | $cookie_secure | #
`protected array` | $data | # Session data Session data
`protected array` | $changedData | #
`protected static mixed` | $default_session | #

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -