EXC | DEV | Documentation | Version 1.0
This topic applies to both the Backend and Front-End frameworks.
Your backend application is ran on a request basis without any persistence of data or variables. EXC uses a session to keep a tab on the state of your application and maintain persistence.
The session allows to store values that are available from one request to another. We use the session for things like: what user is using our app, which record are editing, etc.
In the backend we use the $client
object to store values in the session that are automatically available to our front-end. For example:
<?php
$client = \exc\client::instance();
//save our recordID in the session
$client->session("recordID", $recordID);
In our front-end the app
controller has similar functions to access the session. For example to read the session value "recordID"
we use app.session()
:
var recordID = app.session("recordID");
We can test if a value is already stored in the session using $client->sessionHasKey()
:
<?php
$client = \exc\client::instance();
if($client->sessionHasKey("recordID")){
$recordID = $client->session("recordID"); //get its value
}
In javascript we check if a session value is set in a similar fashion using the app
controller.
if(app.sessionHasKey("recordID")){
console.log("We have a record");
var id = app.session("recordID");
}
Use | PHP Backend | JS Front-end |
---|---|---|
Test if key exists in session. | $client->sessionHasKey($keyName) | app.sessionHasKey(keyName) |
Removes a key from session. | $client->sessionRemove($keyName) | app.sessionRemove(keyName) |
Get value of a session key. | $value = $client->session($keyName) | value = app.session(keyName) |
Sets the value of a session key. | $client->session($keyName, $value) | app.session(keyName, value) |
Note: On the front-end none of the session functions (app.session()
orapp.sessionRemove()
) will modify the session data on the backend.
Given the nature of web apps, EXC is designed to reduce the ability of malicious individuals to tamper with your session data.
Like with any web application is a good design principle to consider all of your front-end data untrusted.
The session data that we manage with $client
in your backend is pushed to your front-end on each interaction, like a one-way synchronization.
By design setting the value of a session key in your front-end using app.session(key,value)
will NOT update the value on the session managed by the backend. Values stored in front-end are saved locally in the browser using the sessionStorage and are available as long as the browser remains open.
In many instances it is important to keep session data privately in the backend, specially for security reasons, the less data we expose in the front-end the best.
The \exc\session
class allows you to store and manage session data.
<?php
//save our recordID in the session
\exc\session::key("recordID", $recordID);
//check if key is in the session
if(\exc\session::hasKey("recordID")){
//read our key
$recordID = \exc\session::key("recordID");
}
While values managed using the session functions found in $client
are synchronized with the front-end, \exc\session
is strictly for storing values on the backend.
Functions of \exc\session
:
Function | Description1 |
---|---|
key($keyName) | Returns the value of a key if exists, else returns null . |
key($keyName, $value) | Store a value in the session. |
hasKey($keyName) | Returns true is a value is stored in the session. |
removeKey($keyName) | Removes a value from the session. |
destroy() | Removes all values and resets the session. |
NOTE Internally the$client
session uses\exc\session
to store its values under the key"ms"
, which is itself an array of key-value pairs.