IHP Api Reference
Copyright(c) digitally induced GmbH 2021
Safe HaskellSafe-Inferred

IHP.Controller.Session

Description

The session provides a way for your application to store small amounts of information that will be persisted between requests. It’s mainly used from inside your controller actions.

In general, you should not store complex data structures in the session. It’s better to store scalar values in there only. For example: Store the current user-id instead of the current user record.

The session works by storing the data inside a cryptographically signed and encrypted cookie on the client. The encryption key is generated automatically and is stored at Config/client_session_key.aes. Internally IHP uses the clientsession library. You can find more technical details on the implementation in the clientsession documentation.

The cookie max-age is set to 30 days by default. To protect against CSRF, the SameSite Policy is set to Lax.

Synopsis

Session Error

data SessionError Source #

Types of possible errors as a result of requesting a value from the session storage

Constructors

NotFoundError

Value not found in the session storage

ParseError String

Error occurce during parsing value

Instances

Instances details
Show SessionError Source # 
Instance details

Defined in IHP.Controller.Session

Methods

showsPrec :: Int -> SessionError -> ShowS #

show :: SessionError -> String

showList :: [SessionError] -> ShowS #

Eq SessionError Source # 
Instance details

Defined in IHP.Controller.Session

Interacting with session store

setSession :: (?context :: ControllerContext, Serialize value) => ByteString -> value -> IO () Source #

Stores a value inside the session:

action SessionExampleAction { userId } = do
    setSession "userId" userId

For cases where setSession is used with literals, to avoid type ambiguity, you can use one of the options below

Example: Annotate a literal with a type

action LogoutAction = do
    setSession "userEmail" ("hi@digitallyinduced.com" :: Text)

Example: Using setSession with type application

action LogoutAction = do
    setSession @Text "userEmail" "hi@digitallyinduced.com"

getSession :: forall value. (?context :: ControllerContext, Serialize value) => ByteString -> IO (Maybe value) Source #

Retrives a value from the session:

action SessionExampleAction = do
    userEmail <- getSession @Text "userEmail"
    counter <- getSession @Int "counter"
    userId <- getSession @(Id User) "userId"

userEmail is set to Just' "hidigitallyinduced.com"@ when the value has been set before. Otherwise, it will be Nothing.

If an error occurs while getting the value, the result will be Nothing.

getSessionEither :: forall value. (?context :: ControllerContext, Serialize value) => ByteString -> IO (Either SessionError value) Source #

Retrives a value from the session:

getSession variant, which returns SessionError if an error occurs while getting value from session storage

action SessionExampleAction = do
    counter <- getSessionEither @Int "counter"
    case counter of
        Right value -> ...
        Left (ParseError errorMessage) -> ...
        Left NotFoundError -> ...
        Left VaultError -> ...

deleteSession :: (?context :: ControllerContext) => ByteString -> IO () Source #

Remove session values from storage:

Example: Deleting a userId field from the session

action LogoutAction = do
    deleteSession "userId"

Example: Calling getSession after using deleteSession will return Nothing

setSession "userId" (1337 :: Int)
userId <- getSession @Int "userId" -- Returns: Just 1337

deleteSession "userId"
userId <- getSession @Int "userId" -- Returns: Nothing

getSessionAndClear :: forall value. (?context :: ControllerContext, Serialize value) => ByteString -> IO (Maybe value) Source #

Returns a value from the session, and deletes it after retrieving:

action SessionExampleAction = do
    notification <- getSessionAndClear @Text "notification"

Orphan instances

PrimaryKey table ~ UUID => Serialize (Id' table) Source # 
Instance details

Methods

put :: Putter (Id' table)

get :: Get (Id' table)