version 2.5+. For lesser documentations, visit the offline documentation of such versions.
icore/init application
configuration file. A sample structure below reveals how these parameters are expected to be defined.
USER_TABLE: users;
USER_ID_FIELDNAME: email;
COOKIE_FIELDNAME: cookie;
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 idCOOKIE_FIELDNAME: A database column in USER_TABLE where cookie hash is storedconfig:all command helps to set up all required configuration parameters.
Session class using sample format below :
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
$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_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.
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.
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.
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:
<?php
namespace spoova\mi\windows\Sessions;
use Window;
class UserSession extends Window {
static function frame() {
new Session('user', 'user_cookie', true);
}
}
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
}
}
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 class methods makes it easier to retrieve or access the intialized data.
These methods and their functions are listed and discussed below.
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:
new Session::('user', 'usercookie'); //instance of session
Session::sessionName(); //user
Session::cookieName(); //usercookie
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.
new Session::('user', 'usercookie'); //instance of session
Session::stream(); //fetch the instance of the session back
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.
$data = ['userid' => 'some_id'] //test data User::login($data); //add userid into the session
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.