HTTP Session

Introduction

info

Since HTTP applications are stateless, sessions provide a way to store information about the user across multiple requests.

Usage

Retrieving data

There are two main ways to work with session data in Bow: the global session helper and through a Bow\Http\Request instance.

First, let's look at accessing the session through a Bow\Http\Request instance, which can be injected into a controller method. Remember that controller method dependencies are automatically injected via the Bow container:

namespace App\Controllers;

use App\Controllers\Controller;
use App\Models\User;
use Bow\Http\Request;

class UserController extends Controller
{
  /**
   * Display a user
   *
   * @param Request $request
   * @param int $id
   * @return Response
   */
  public function show(Request $request, $id)
  {
    $value = $request->session()->get('key');

    //
  }
}

When you retrieve an item from the session, you can also pass a default value as the second argument to the get method. 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

The session() helper is a reader (and an accessor to the instance):

• session() — returns the Session instance.
• session('key') — returns the stored value (or null).
• session('key', 'default') — same, with a fallback value.

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

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

  // Store data: go through the instance
  session()->set('key', 'value');
  // or: session()->put('key', 'value');
});

No array form

Unlike some frameworks, session(['key' => 'value']) does not work in Bow and throws a TypeError: the helper only accepts ?string as its first argument. To write, use session()->set(...) or session()->put(...).

Retrieving all session data

If you want to retrieve all the data in the session, you can use the all method:

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

Determining whether an item exists in the session

To determine whether an item is present in the session, you can 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 whether an item is present in the session, even if its value is null, you can use the exists method. The exists method returns true if the item is present:

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

Storing data

To store data in the session, use the set method (or its alias put) on the session instance:

// Through a request instance
$request->session()->set('key', 'value');
$request->session()->put('another', 42);

// Through the helper (which returns the Session instance when called without a key)
session()->set('key', 'value');

Flash data

Information

Sometimes you may want to store items in the session only for the next request. Flash data is mainly useful for short-lived status messages.

You can do this using the flash method or the flash helper. Data stored in the session using this method will only be available during the next HTTP request, then will be deleted.

$request->session()->flash('status', 'Welcome !');

If you need to remove your flash data, you can use the clearFlash method:

$request->session()->clearFlash();

Deleting data

The remove method will delete a piece of data from the session. If you want to delete all the data in the session, you can use the flush method. If, however, you want to delete all the information except the flash information, you can use the clear method:

// Delete a piece of data from the session
$request->session()->remove('key');

// Delete all information except the flash information
$request->session()->clear();

// Delete all the session data
$request->session()->flush();

Is something missing?

If you run into problems with the documentation or have suggestions to improve the documentation or the project in general, please open an issue for us, or send a tweet mentioning the Twitter account @bowframework or directly on github.