Documentation

You are viewing the documentation for the 2.6.20 release in the 2.6.x series of releases. The latest stable release series is 3.0.x.

§Session and Flash scopes

§How it is different in Play

If you have to keep data across multiple HTTP requests, you can save them in the Session or Flash scopes. Data stored in the Session are available during the whole user Session, and data stored in the Flash scope are available to the next request only.

It’s important to understand that Session and Flash data are not stored by the server but are added to each subsequent HTTP request, using the cookie mechanism. This means that the data size is very limited (up to 4 KB) and that you can only store string values. The default name for the cookie is PLAY_SESSION. This can be changed by configuring the key play.http.session.cookieName in application.conf.

If the name of the cookie is changed, the earlier cookie can be discarded using the same methods mentioned in Setting and discarding cookies.

Of course, cookie values are signed with a secret key so the client can’t modify the cookie data (or it will be invalidated).

The Play Session is not intended to be used as a cache. If you need to cache some data related to a specific Session, you can use the Play built-in cache mechanism and store a unique ID in the user Session to keep them related to a specific user.

§Session Configuration

Please see Configuring Session Cookies for more information for how to configure the session cookie parameters in application.conf.

§Session Timeout / Expiration

By default, there is no technical timeout for the Session. It expires when the user closes the web browser. If you need a functional timeout for a specific application, you set the maximum age of the session cookie by configuring the key play.http.session.maxAge in application.conf, and this will also set play.http.session.jwt.expiresAfter to the same value. The maxAge property will remove the cookie from the browser, and the JWT exp claim will be set in the cookie, and will make it invalid after the given duration. Please see Configuring Session Cookies for more information.

§Storing data in the Session

As the Session is just a Cookie, it is also just an HTTP header. You can manipulate the session data the same way you manipulate other results properties:

Ok("Welcome!").withSession(
  "connected" -> "[email protected]")

Note that this will replace the whole session. If you need to add an element to an existing Session, just add an element to the incoming session, and specify that as new session:

Ok("Hello World!").withSession(
  request.session + ("saidHello" -> "yes"))

You can remove any value from the incoming session the same way:

Ok("Theme reset!").withSession(
  request.session - "theme")

§Reading a Session value

You can retrieve the incoming Session from the HTTP request:

def index = Action { request =>
  request.session.get("connected").map { user =>
    Ok("Hello " + user)
  }.getOrElse {
    Unauthorized("Oops, you are not connected")
  }
}

§Discarding the whole session

There is special operation that discards the whole session:

Ok("Bye").withNewSession

§Flash scope

The Flash scope works exactly like the Session, but with two differences:

Important: The Flash scope should only be used to transport success/error messages on simple non-Ajax applications. As the data are just kept for the next request and because there are no guarantees to ensure the request order in a complex Web application, the Flash scope is subject to race conditions.

Here are a few examples using the Flash scope:

def index = Action { implicit request =>
  Ok {
    request.flash.get("success").getOrElse("Welcome!")
  }
}

def save = Action {
  Redirect("/home").flashing(
    "success" -> "The item has been created")
}

To retrieve the Flash scope value in your view, add an implicit Flash parameter:

@()(implicit flash: Flash)
...
@flash.get("success").getOrElse("Welcome!")
...

And in your Action, specify an implicit request => as shown below:

def index = Action { implicit request =>
  Ok(views.html.index())
}

An implicit Flash will be provided to the view based on the implicit request.

If the error ‘could not find implicit value for parameter flash: play.api.mvc.Flash’ is raised then this is because your Action didn’t have an implicit request in scope.

Next: Body parsers