Session

Since HTTP driven applications are stateless, sessions provide a way to store information about the user across multiple requests. Atom ships with a variety of session backends that are accessed through an expressive, unified API. By default, sessions are stored in storage/framework/sessions.

Using The Session

There are two primary ways of working with session data in Atom: the global session helper and via a Request instance. First, let's look at accessing the session via a Request instance:

$value = request()->session()->get('key');

When you retrieve an item from the session, you may also pass a default value as the second argument to the getmethod. This default value will be returned if the specified key does not exist in the session. If you pass a Closure as the default value to the get method and the requested key does not exist, the Closure will be executed and its result returned:

$value = request()->session()->get('key', 'default');

$value = request()->session()->get('key', function () {
    return 'default';
});

The Global Session Helper

You may also use the global session PHP function to retrieve and store data in the session. When the session helper is called with a single, string argument, it will return the value of that session key. When the helper is called with an array of key / value pairs, those values will be stored in the session:

router()->get('home', function () {
    // Retrieve a piece of data from the session...
    $value = session('key');

    // Specifying a default value...
    $value = session('key', 'default');

    // Store a piece of data in the session...
    session(['key' => 'value']);
});

Retrieving All Session Data

If you would like to retrieve all the data in the session, you may use the all method:

$data = request()->session()->all();

Determining If An Item Exists In The Session

To determine if an item is present in the session, you may use the has method. The has method returns true if the item is present and is not null:

if (request()->session()->has('users')) {
    //
}

To determine if an item is present in the session, even if its value is null, you may use the exists method. The existsmethod returns true if the item is present:

if (request()->session()->exists('users')) {
    //
}

Storing Data

To store data in the session, you will typically use the put method or the session helper:

// Via a request instance...
request()->session()->put('key', 'value');

// Via the global helper...
session(['key' => 'value']);

Pushing To Array Session Values

The push method may be used to push a new value onto a session value that is an array. For example, if the user.teamskey contains an array of team names, you may push a new value onto the array like so:

request()->session()->push('user.teams', 'developers');

Retrieving And Deleting An Item

The pull method will retrieve and delete an item from the session in a single statement:

$value = request()->session()->pull('key', 'default');

Deleting Data

The forget method will remove a piece of data from the session. If you would like to remove all data from the session, you may use the flush method:

// Forget a single key...
request()->session()->forget('key');

// Forget multiple keys...
request()->session()->forget(['key1', 'key2']);

request()->session()->flush();

Regenerating The Session ID

Regenerating the session ID is often done in order to prevent malicious users from exploiting a session fixation attack on your application.

request()->session()->regenerate();