Session configuration
The documentation provided on this page are strictly for spoova version 2.5+. For lesser documentations, visit the offline documentation of such versions.
Sessions in spoova are managed by the default php session storage system. In this system, session is controlled through the use of session keys. These keys provides an easy communication between sessions and stored database information. They make it easier for session to pull its user data from a relative database storage system. The configuration of session is done in two stages. These stages are listed and discussed below.

Session File Configuration

The default parameters required by the session controller class are parameters which are required for mapping selected database to session accounts. These parameters provide a basic information for the session manager which allows it to be able to understand where informations are stored and how best to manage them. The parameters are defined in the icore/init application configuration file. A sample structure below reveals how these parameters are expected to be defined.
Init File Sample Format
  USER_TABLE: users;
  USER_ID_FIELDNAME: email;
  COOKIE_FIELDNAME: cookie;                    
                                    
The configuration keys and values pairs above are explained below:
USER_TABLE: This table is expected to be the user table where user data is stored.
USER_ID_FIELDNAME: A database column in USER_TABLE that contains the user unique id
COOKIE_FIELDNAME: A database column in USER_TABLE where cookie hash is stored
By default, during project installation, the config:all command helps to set up all required configuration parameters.
Session Keys Configuration
The next major activity after default session configuration is the setting up of session controller keys. These controller keys are defined at the top level of the application because they define session storage names that are used to store and manage session data and they further provide handshake between session data and user data stored within the database storage system. The controller keys are defined immediately the session is initialized. Hence, this will be further discussed under session initialization.
Session Initialization
The session controller keys are defined at the instantiation of the Session class using sample format below :

Syntax: Session class initialization
  new Session($session_key, $cookie_key, $secure);

  
  where: 
    
    $session_key       : a data access key referring to where session data is stored on.

    $cookie_key        : a data access key referring to where cookie hash data for rememberMe is stored.

    $secure (optional) : a boolean value that defines if a session should be strictly secured (or validated).

    
    Note: For the purpose of this documentation

    session_key => $session_key 

    cookie_key  => $cookie_key 

    secure      => $secure
  
                                    
The session class requires that a $session_key should be defined. This key can be or any string but it is advisable to use alphnumerical values for easy access. Th key is used by the User class to store data when the User::login() method is called. The $cookie_key, though optional, helps the $_COOKIE global variable to identify where to store a session user's cookie hash key which is mostly used for remember me. Once both arguments are defined, The entire relationship between the $_SESSION and $_COOKIE class will then be synced making it easier to either log in or log out of a session.


Session(session_key)
The session_key value is the first argument of the Session class that must be defined during initialization. It refers to a session access key that points to where user data is stored within the global session storage. This key is mostly used for storing and retrieving session data and it is expected to be a valid aphanumerical string.

Session(cookie_key)
Just like the session_key, the cookie_key is used by the global cookie storage to store a user cookie which is mostly used for rememberMe. Although, defining this key is optional, it is mostly required even if it is not used. When this value is defined, we can easily remember active sessions. Also, it makes it easier to set up user registration forms with a rememberMe feature by adding an extra input field with the name of "remember" which is submitted along with form requests. If a session is logged out but its access cookie is active, the session class will look for the active value in the database table's field relative to COOKIE_FIELD_NAME declared in the init file. This value will help to log the user back if the hashed value stored is active. It is important to note that setting this argument requires that a COOKIE_FIELD_NAME key is already predefined in the init configuration file and the value of this key is expected to be a field in the user's database table where cookie hashes and values are either saved or obtained from.

Session(secure)
The secure argument which is the third argument of the Session instance deals more with session management. It is a way by which a layer of security can be added to the session in such a way that the "userid" stored in session must exist in database. This ensures that a fake id cannot create an active session. By setting the "secure" argument as true, the Session class will validate the userid stored within the session class. If the value does not exist in the USER_ID_FIELDNAME database column name defined in init file, the session will be nullified. The Session::secure() method can also be used to achieve the same effect and it takes the argument of true or false. In order to validate the userid of the current session user, the database connection must be active.

Session linkage
In order to have access to the session class, we need a way to link the session to routes which in turn makes use of these session information. In earier versions of the framework, the linking of a session to routes can be done through session channels. However, starting from version 2.5, we can start our session using the window's frame() method which is inherited from the root Window class. An example is shown below:

Session: Instantiation
  <?php

  namespace spoova\mi\windows\Sessions;

  use Window;

  class UserSession extends Window {

    static function frame() {

        new Session('user', 'user_cookie', true);

    }

  }
                                        
The sample above illustrates how to initialize the Session class from a session frame file. While the first argument and second argument are mostly required, the third is not required unless we want the Session class to always validate the session id. This validation means that any detected session id must be found within the database field value specified as USER_ID_FIELDNAME in the init file. If this value is not detected, the session unique id value will be rejected, forcing a nullified session. Once we define our session as shown above, we can then link to the session instance within routes files just as shown below:
  <?php

  namespace spoova\mi\windows\Routes\Home;

  use Window;
  use spoova\mi\windows\Sessions\UserSession;

  class Home extends UserSession {


    function __construct() {

        vdump(User::config()); // view configuration

    }


  }
                                    
In the Home route above, we linked to the session through the UserSession class. Once we successfully link the route, we can use the User::config() method to detect if the session is successfully linked. The array returned which has two keys which are SESSION_NAME and COOKIE_NAME should have their values as "user" and "user_cookie" respectively. Once these values are displayed, it means the configuration keys are successfully defined and accessible. We can also obtain any of these keys by using Session::sessionName() or Session::cookieName() respectively or we can do this similarly through the User class with User::sessionName() and User::cookieName() methods.
Session Keys Methods

Once the session is properly initialized, some useful Session class methods makes it easier to retrieve or access the intialized data. These methods and their functions are listed and discussed below.

sessionName() and cookieName()
The Session::sessionName() and Session::cookieName() as explained earlier, are both methods that retrives the session_key and cookie_key storage key names once defined. Example of this is shown below:
Syntax: sessionName(), cookieName()
  new Session::('user', 'usercookie'); //instance of session 

  Session::sessionName(); //user   

  Session::cookieName(); //usercookie    
                                            
Session::stream()
The Session::stream() method is used to return the last instance of the session class. This can be after the User class or the session class is instantiated. Mostly, the session is defined once at the top of the application, in order to access this instance, we can use the stream() method later in the application.
Syntax: Session::stream
  new Session::('user', 'usercookie'); //instance of session 

  Session::stream(); //fetch the instance of the session back    
                                            
Session::userid()
The Session::userid() method is used to fetch the current user id of the session class. Once a session is active, the userid can easily be obtained through the use of this method as long as the session contains the specified session userid key. Once the user session is successfully created through the User::login() method, we can easily obtain the user id of the current session by calling the User::id() or the Session::userid() method. The sample below shows how the user id can be added such that it can be obtained later.
Syntax: Session::userid()
  $data = ['userid' => 'some_id'] //test data 

  User::login($data); //add userid into the session    
                                            
In the code sample above, the User::login() will try to set the userid of the current user through the specified array key "userid". If the session is set as secure, the session class will go on to validate the specified id. If the id (i.e some_id) corresponds to the id of the user in the pre-configured user table, and preconfigured id field, then the id will be accepted and we can obtain the user id back through the User::id() or Session::id(). However, if the id cannot be validated, it will be nullified making it impossible to fetch the specified user id. If the secure part of the session is set as false or not specified during instantiation, the session id will not be validated.