Documentation(EN)

Installation

The best way to install O2Session is to use Composer

composer require o2system/o2session:"dev-master"

Initializing a Session

Sessions will typically run globally with each page load, so the Session class should either be initialized in your application bootstrap. For the most part the session class will run unattended in the background, so simply initializing the class will cause it to read, create, and update sessions when necessary.

use O2System\Session;

$session = new Session(array(
    'storage' => array(
        'name' => 'session_name',
        'driver' => 'files',
        'save_path' => 'path/to/session/storage',
        'lifetime' => 3600,
        'regenerate_time' => 600,
        'regenerate_id' => FALSE,
        'match_ip' => TRUE
    ),
    'cookie' => array(
        'prefix' => 'cookie_',
        'lifetime' => 7200,
        'domain' => '',
        'path' => '/',
        'secure' => FALSE,
        'httponly' => TRUE
    )
));

$session will be used as an example variable at this documentation page.

Set Session Data

Assign data into session userdata array.

/*
 * @param string  $item   An array of key/value pairs to set as session data, or the key for a single item.
 * @param mixed   $value  The value to set for a specific session item, if $data is a key.
 *
 * @return void
 */
// method 1:
$session->set_userdata('ITEM_NAME', 'ITEM_VALUE');

// method 2:
$session->set_userdata(array(
    'username' => 'o2system',
    'email' => 'user@o2system.in,
    'is_logged_in' => TRUE
));

Any data that we assign to the session userdata will be available also in Native PHP $_SESSION Superglobal.

Get Session Data

Gets the value for a specific $_SESSION item, or an array of all “userdata” items if not key was specified.

/*
 * @param string|null  $item   Session item key or NULL
 *
 * @return mixed|null
 */
// method 1 (using userdata method):
$session->userdata('ITEM_NAME');    // for backwards compatibility, through userdata() method

// method 2 (using magic getter):
$session->{'ITEM_NAME'};

// method 3 (native PHP Session):
$_SESSION['ITEM_NAME'];

Where 'item' is the array key corresponding to the item you wish to get.

Verify Session Data

Verify the value of the session based on the key name of the session userdata array.

/*
 * @param string  $item Session item key
 *
 * @return bool
 */
$session->has_userdata('ITEM_NAME');

// Using Native PHP Session Variable
isset($_SESSION['ITEM_NAME'])

Remove Session Data

Remove a session value of session userdata array, based on array key name.

/*
 * @param string|array  $item Key for the session data item to unset, or an array of multiple keys.
 *
 * @return bool
 */
// Single Removal
// method 1:
$session->unset_userdata('ITEM_NAME');

// method 2:
unset($_SESSION['ITEM_NAME']);

// Multiple Items Removal
$session->unset_userdata(['ITEM_1', 'ITEM_2');

// method 2:
unset($_SESSION['ITEM_1'], $_SESSION['ITEM_2']);

Flash Session Data

Marks a session userdata item key (or multiple ones) as "flashdata".

/*
 * @param string|array  $item Key to mark as "flashdata", or an array of multiple keys.
 *
 * @return bool
 */
// Single Flash Marking
// method 1:
$session->mark_flashdata('ITEM_NAME');

// Multiple Flash Marking
$session->mark_flashdata(['ITEM_1', 'ITEM_2');

Unset Flash Session Data

Unmarks a session userdata item key (or multiple ones) as "flashdata".

/*
 * @param string|array  $item Key to mark as "flashdata", or an array of multiple keys.
 *
 * @return bool
 */
// Single Flash Marking
// method 1:
$session->unset_flashdata('ITEM_NAME');

// Multiple Flash Marking
$session->unset_flashdata(['ITEM_1', 'ITEM_2');

Get Flash Session Data Keys

Gets a list of all session userdata that have been marked as "flashdata".

/*
 * @return array Array containing the keys of all "flashdata" items.
 */
$session->get_flash_keys();

Get Flash Session Data

Gets the value for a specific session userdata item that has been marked as "flashdata", or an array of all "flashdata" items if no key was specified.

/*
 * @param string|null $item Flashdata item key or NULL
 *
 * @return mixed Value of the specified item key, or an array of all "flashdata"
 */
$session->flashdata('ITEM_NAME');

Keep Flash Session Data

Retains the specified session userdata key(s) as "flashdata" through the next request.

/*
 * @param string|array $item Flashdata key to keep, or an array of multiple keys
 *
 * @return bool
 */
// Single Item Retaining
$session->keep_flashdata('ITEM_NAME');

// Multiple Items Retaining
$session->keep_flashdata(['ITEM_1', 'ITEM_2']);

Set Flash Session Data

Assigns data to the session userdata and marks it as "flashdata".

/*
 * @param string  $item   An array of key/value pairs to set as session data, or the key for a single item.
 * @param mixed   $value  The value to set for a specific session item, if $data is a key.
 *
 * @return void
 */
// method 1:
$session->set_flashdata('ITEM_NAME', 'ITEM_VALUE');

// method 2:
$session->set_flashdata(array(
    'foo' => 'bar',
    'message' => 'flash message'
));

Temp Session Data

Marks a session userdata item key (or multiple ones) as "tempdata".

/*
 * @param string|array  $item Key to mark as "tempdata", or an array of multiple keys.
 * @param int           $ttl  Time-to-live value for the tempdata, in seconds
 *
 * @return bool
 */
// Single Temp Marking
// method 1:
$session->mark_tempdata('ITEM_NAME', 300);

// Multiple Temp Marking
$session->mark_tempdata(['ITEM_1', 'ITEM_2', 300);

Unset Temp Session Data

Unmarks a session userdata item key (or multiple ones) as "tempdata".

/*
 * @param string|array  $item Key to mark as "tempdata", or an array of multiple keys.
 *
 * @return bool
 */
// Single Flash Marking
// method 1:
$session->unset_tempdata('ITEM_NAME');

// Multiple Flash Marking
$session->unset_tempdata(['ITEM_1', 'ITEM_2');

Get Temp Session Data Keys

Gets a list of all session userdata that have been marked as "tempdata".

/*
 * @return array Array containing the keys of all "flashdata" items.
 */
$session->get_temp_keys();

Get Temp Session Data

Gets the value for a specific session userdata item that has been marked as "tempdata", or an array of all "tempdata" items if no key was specified.

/*
 * @param string|null $item Tempdata item key or NULL
 *
 * @return mixed Value of the specified item key, or an array of all "tempdata"
 */
$session->tempdata('ITEM_NAME');

Set Temp Session Data

Assigns data to the session userdata and marks it as "tempdata".

/*
 * @param string  $item   An array of key/value pairs to set as session data, or the key for a single item.
 * @param mixed   $value  The value to set for a specific session item, if $data is a key.
 *
 * @return void
 */
// method 1:
$session->set_tempdata('ITEM_NAME', 'ITEM_VALUE');

// method 2:
$session->set_tempdata(array(
    'foo' => 'bar',
    'message' => 'flash message'
));

Check Is Session Started

Check if session has been started.

/*
 * @return bool
 */
$session->is_started();

Regenerate Session ID

Regenerate session ID, optionally destroying the current session's data.

/*
 * @param bool $destroy Whether to destroy session data
 */
$session->regenerate_id(TRUE);

Destroy Session

Destroys the current session.

/*
 * @param bool $destroy Whether to destroy session data
 */
$session->regenerate_id(TRUE);