SOURCE

UserSession.php

Classes


UserSession

class UserSession

{

Implements the "web by functions" web programming paradigm, also known as bt_ to create the so called "one page web application". Some basic concepts:

The single public page, say index.php, should set the static properties of this class, then it should instantiate an object. This is the dispatcher page.

The constructor takes care to create a new user session, or resume an existing session, then invokes the requested function, or sends back to the dashboard function, or serves the login page, depending on the validity of the request and the availability of the session.

Each user session includes one or more windows sessions, so that several independent pages at once can be managed for each user.

Several storage area are created: application parameters (permanent); users' parameters (permanents), user session parameters (shared among all the windows), windows parameters (specific of the window).

Pages are generated by functions. The methods anchor() and button() create clickable entities to invoke some other function (from here on named "forward calls"). The name of these functions and their arguments are never sent to the remote client, though. For example, the page page1 creates an anchor to invoke page2:

class MyApp {

	static function page1()
	{
		echo "<html><body>Hello, I'm page 1 ";
		UserSession::anchor("See page 2", "MyApp::page2");
		echo "</body></html>";
	}

	static function page2()
	{
		echo "<html><body>Hello, I'm page 2 ";
		UserSession::anchor("See page 1", "MyApp::page1");
		echo "</body></html>";
	}

}

Class autoloading greatly simplifies the task of the dispatcher of finding each required class at the right time.

Invoked functions (here named "forward calls") can be regular functions or static methods as well. Their name and their arguments are serialized and saved in the "bt file", a file specific of each window session. Each window takes a number "w", and each entry in the bt file takes a number "i"; you may recognize these numbers in the generated URLs.

A concept of stack of "backward calls" is also implemented and saved in each window session. So, if pages are served by functions, these pages (that is, functions) may remember the order of their invocation and may return results to their invoker.

A tutorial about bt_ is available at http://www.icosaedro.it/phplint/web.
Author: Umberto Salsi <salsi@icosaedro.it>
Copyright: Copyright 2018 by icosaedro.it di Umberto Salsi
Version: $Date: 2020/02/27 17:45:29 $

Properties


$BASE_DIR

public static string $BASE_DIR

Directory where sessions, users preferences and application preferences are saved. A distinct directory should be created for each web app. BEWARE. Sensitive data are stored here, so the access permissions must be the lowest possible.


$COOKIE_NAME

public static string $COOKIE_NAME

Name of the session cookie. When two or more distinct web app have to be managed on the same server, the name of the session cookie MUST be different for each app! BEWARE. Some characters are mangled by PHP while retrieving cookies, so only set a name which is also a valid PHP identifier.


$DASHBOARD_FUNCTION

public static string $DASHBOARD_FUNCTION

URL of the user's dashboard function. It can also be the bare path of the resource, for example "/dashboard.php".


$DISPATCHER_URL

public static string $DISPATCHER_URL

URL of the page performing the dispatching of the client requests. Anchors and form actions will use this URL. The dispatcher page should simply instantiate this object, which in turn will renew the session cookie and will call the requested forward call function.


$LOGIN_URL

public static string $LOGIN_URL

URL of the login page. It can also be the bare path of the resource, for example "/login.php".


$SECURE

public static boolean $SECURE

If the cookie has to be sent and accepted only over a secure HTTPS connection. Normally TRUE.

Methods


__construct()

public void __construct(string $login_name) throws UserSessionInvalidHttpMethodException, Exception

Initializes or resumes the user's session and perform request dispatching. First, all the working directories beneath the base directory are created. BEWARE: all the static properties of this class must be set before instantiating this object.

Then, if the user name is give, tries to create a new user session and invokes the dashboard.

If the user name is null, tries to resume the users' session based on the request. If no valid session is found in the request, redirects to the login page. If a valid session is found, invokes the call forward function of the request. Finally, if no valid call forward is found, invokes the dashboard of the user.
Parameters:
$login_name - Name of the user just logged-in. If NULL or empty, tries to resume the user's session based on the current session cookie. If no valid session is available, redirects to the login page.
Throws:
UserSessionInvalidHttpMethodException - Unsupported HTTP method; expected either "GET" or "POST".


addAttributes()

public static void addAttributes(string $value)

Set further attributes for the next anchor, form or button HTML element. Once used, the value will be reset to the empty string.
Parameters:
$value - Verbatim string to add to the element, for example: "id='save_button' class='my_button_style'".


anchor()

public static void anchor(string $text_html, string $func, args) throws RuntimeException

Sends to standard output an HTML anchor entity which, if clicked by user, triggers the invocation of the specified forward call function. Inside a currently open form, performs a postback of the form data (JavaScript is required in order for this to work, though).
Parameters:
$text_html - HTML text the user will read.
$func - Function to call if this anchor is clicked; arguments may follow.


button()

public static void button(string $text, string $func, args) throws RuntimeException

Sends to standard output an HTML button entity which, if clicked by user, triggers the invocation of a forward call function.
Parameters:
$text - Text the user will read inside the button.
$func - Function to call if this button is clicked. Function arguments may follow.
Throws:
RuntimeException - No currently open form. Failed accessing the file system.


formClose()

public static void formClose() throws RuntimeException

Sends to standard output the HTML form closing entity.
Throws:
RuntimeException - No currently open form.


formOpen()

public static void formOpen() throws RuntimeException

Sends to standard output the HTML form opening entity.
Throws:
RuntimeException - Form already open.


getApplicationParameter()

public static string getApplicationParameter(string $name, string $def = NULL) throws RuntimeException

Retrieves an application parameter. If the parameter is missing, the default value is returned instead, otherwise it is an exception.
Parameters:
$name - Name of the parameter.
$def - Default value returned if the parameter is missing.
Return: Value of the parameter.
Throws:
RuntimeException - Parameter is missing and no default value set. Failed accessing file.


getSessionParameter()

public static string getSessionParameter(string $name, string $def = NULL) throws RuntimeException

Retrieves a parameter from the user's session. If the parameter is missing, the default value is returned instead, otherwise it is an exception.
Parameters:
$name - Name of the parameter.
$def - Default value returned if the parameter is missing.
Return: Value of the parameter.
Throws:
RuntimeException - Parameter is missing and no default value set. Failed accessing file.


getUserPreferenceParameter()

public static string getUserPreferenceParameter(string $name, string $def = NULL) throws RuntimeException

Retrieves an user's preference parameter. If the parameter is missing, the default value is returned instead, otherwise it is an exception.
Parameters:
$name - Name of the parameter.
$def - Default value returned if the parameter is missing.
Return: Value of the parameter.
Throws:
RuntimeException - Parameter is missing and no default value set. Failed accessing file.


getWindowParameter()

public static string getWindowParameter(string $name, string $def = NULL) throws RuntimeException

Retrieves a parameter from the window's session. If the parameter is missing, the default value is returned instead, otherwise it is an exception.
Parameters:
$name - Name of the parameter.
$def - Default value returned if the parameter is missing.
Return: Value of the parameter.
Throws:
RuntimeException - Parameter is missing and no default value set. Failed accessing file.


invokeCallBackward()

public static void invokeCallBackward(args)

Invoke the function on the top of the bt stack. Further arguments can be added.


link()

public static string link(string $func, mixed[int] $args_) throws ErrorException

Returns an URL to invoke a specific forward call function.
Parameters:
$func - Name of the forward call.
$args_ - Arguments of the function.
Return: URL to the dispatcher page that invokes this forward call.


logout()

public static void logout()

Delete user's session. If a session was already set, delete the session and sends the user to the login page. The browser's cookie is always deleted.


setApplicationParameter()

public static void setApplicationParameter(string $name, string $value) throws RuntimeException

Saves an application parameter.
Parameters:
$name - Name of the parameter.
$value - Value of the parameter.
Throws:
RuntimeException - Failed accessing the file system.


setCallBackward()

public static void setCallBackward(string $func, args)

Sets the call-backward for the next forward call. Invoke this method to prepare a return point after an anchor or button. This call-backward will be put on top of the bt stack before invoking the forward call it is associated to.
Parameters:
$func - Name of the call-backward function; arguments may follow.


setDefaultCallForward()

public static void setDefaultCallForward()

Marks the next forward call as the default forward call of the bt file to invoke if the "i" parameter is invalid. If the user retrieves pages from the browser history trying to subvert the navigation path set by the application, this default call forward should represent the safer choice in the current form, typically a button like Cancel or Dismiss or OK.
BEWARE: do not set as default forward call a function that retrieves form data because the request may contain arbitrary fields from expired pages.


setSessionParameter()

public static void setSessionParameter(string $name, string $value) throws RuntimeException

Saves an user's session parameter.
Parameters:
$name - Name of the parameter.
$value - Value of the parameter.
Throws:
RuntimeException - Failed accessing the file system.


setUserPreferenceParameter()

public static void setUserPreferenceParameter(string $name, string $value) throws RuntimeException

Saves an user's preference parameter. These parameters are permanently stored on the file system and are shared among all the session of the current user.
Parameters:
$name - Name of the parameter.
$value - Value of the parameter.
Throws:
RuntimeException - User's session not available. Failed accessing the file system.


setWindowParameter()

public static void setWindowParameter(string $name, string $value) throws RuntimeException

Saves a window's session parameter.
Parameters:
$name - Name of the parameter.
$value - Value of the parameter.
Throws:
RuntimeException - Failed accessing the file system.


stackPop()

public static mixed[int] stackPop() throws ErrorException, RuntimeException

Returns the top of the stack for the current window session.
Return: The first element is the name of the call-backward function, the remaining elements are its arguments.
Throws:
ErrorException - Failed accessing the file system.
RuntimeException - The stack is empty.


stackPush()

public static void stackPush(string $func, mixed[int] $args_)

Appends a call-backward to the bt stack of the current window session.


stackReset()

public static void stackReset()

Resets the stack. The dashboard page of the web site may want to reset the stack to remove pending stale entries. See also comments to the UserSession::setDefaultCallForward() method.


Private constants: DEFAULT_CALL_FORWARD

Private properties: $add_attributes, $cookie_value, $form_open, $postback_button_id, $session_duration, $session_parameters_cache, $us, $user_session_dir, $users_dir, $users_sessions_dir, $window_session

Private methods: deleteDirectory(), isSessionAvailable(), isValidSessionValueFormat(), login(), postback(), setCookie(), staleSessionsCleanup()
}

Requirements

PHP Version: 7

Required modules: array, core, file, openssl, pcre, phpinfo, spl, zlib

Required packages:

../../../../AutoloadException.php
../../../../CastException.php
../../../../InternalException.php
../../../../UnimplementedException.php
../../../../all.php
../../../../autoload.php
../../../../cast.php
../../../../errors.php
../../cast/ArrayBothType.php
../../cast/ArrayIntType.php
../../cast/ArrayStringType.php
../../cast/BooleanType.php
../../cast/ClassType.php
../../cast/FloatType.php
../../cast/IntType.php
../../cast/MixedType.php
../../cast/NullType.php
../../cast/ObjectType.php
../../cast/ResourceType.php
../../cast/StringType.php
../../cast/TypeInterface.php
../../cast/Types.php
../../containers/Printable.php
../../utils/Random.php
../../utils/SecureRandom.php
../Http.php
../Log.php
UserSessionInvalidHttpMethodException.php
WindowSession.php
WindowSessionConcurrentAccessException.php

Generated by PHPLint Documentator