Session guide

The Session module provides a session tracking and session storage mechanism.

When using the Session module, each visitor to your web app is assigned a random and secure unique identifier, and you'll be able to keep track of their activity across requests, and store visitor-specific data.

The most obvious use of a session mechanism like this is to implement a login system to let your users identify themselves with some sort of password, and give them access to their private sections and functionalities. This is exactly what the Login module does using Session.

But you can use the Session module for many other purposes. Let's see how.

Setting up the Session database table

The Session module uses the cherrycake_session table in the database to store the sessions information.

You can create the Session table in your database by importing the session.sql file you'll find in the Cherrycake skeleton repository, under the install/database directory.

Because Session needs a connection to a database, you need to set it but by creating a /config/Database.config.php file just like we did in the Database guide.

Working with Session

First, let's remember our simple Hello world web app, which worked with this basic HelloWorld app module:

<?php

namespace CherrycakeApp\Modules;

class HelloWorld extends \Cherrycake\Module {

    public static function mapActions() {
        global $e;
        $e->Actions->mapAction(
            "home",
            new \Cherrycake\ActionHtml([
                "moduleType" => \Cherrycake\ACTION_MODULE_TYPE_APP,
                "moduleName" => "HelloWorld",
                "methodName" => "show",
                "request" => new \Cherrycake\Request([
                    "pathComponents" => false,
                    "parameters" => false
                ])
            ])
        );
    }
    
    function show() {
        global $e;
        $e->Output->setResponse(new \Cherrycake\ResponseTextHtml([
            "code" => \Cherrycake\RESPONSE_OK,
            "payload" =>
                $e->HtmlDocument->header().
                "Hello world!".
                $e->HtmlDocument->footer()
        ]));
    }
    
}

Note we've updated the show method to use the HtmlDocument module to create the HTML document structure, now that we learned how it works in the HtmlDocument Guide.

Now, to use the Session module, you first need to add it to the list of your core module dependencies, like this:

class HelloWorld extends \Cherrycake\Module {
    protected $dependentCoreModules = [
        "Session"
    ];

    ...    
}

Now, let's say we want to show how many times the visitor has seen the Hello World page. We'll do this by storing the views counter in the visitor's session, like this:

function show() {
    global $e;
    
    $e->Session->numberOfTimesViewed ++;
    
    $e->Output->setResponse(new \Cherrycake\ResponseTextHtml([
        "code" => \Cherrycake\RESPONSE_OK,
        "payload" =>
            $e->HtmlDocument->header().
            "You've seen this page {$e->Session->numberOfTimesViewed} times".
            $e->HtmlDocument->footer()
    ]));
}

Now, every time a visitor reloads the page they'll see the counter growing:

You've seen this page 2 times

See this example working in the Cherrycake documentation examples site.