HTTP Session in BowPHP

• Introduction
• Usage
  • Retrieving data
  • The global session helper
  • Retrieving all session data
  • Determining whether an item exists in the session
  • Storing data
• Flash data
• Deleting data

Introduction

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 type-hinted on a controller method. Remember that controller method dependencies are automatically injected via the Bow container:

App\Controller;

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

You can 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 returns the value of that session key. When the helper is called with an array of key/value pairs, those values are stored in the session:

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

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

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

Retrieving all session data

If you want to retrieve all the session data, 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, you will generally use the put method or the session helper.

// Via a request instance
$request->session()->set('key', 'value');

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

Flash data

Sometimes you may want to store items in the session only for the next request. 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. Flash data is primarily useful for short-lived status messages:

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

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

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

Deleting data

The remove method will delete a value from the session. If you want to delete all session data, you can use the flush method. If, on the other hand, you want to delete all information except the flash information, you can use the clear method:

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

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

// Delete all 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.