Skip to main content

Session lib

This guide documents the session class library used in the AVRO framework to manage PHP sessions in a safe, consistent way.

The library wraps native PHP session handling with a simple API for setting, getting, and removing values, supports namespaced "sections", and adds basic security hardening.

Notes:

  • Sessions are automatically started by the library when it is instantiated.
  • A configurable prefix is applied to all keys stored in $_SESSION to avoid collisions across applications.
  • Security measures:
    • Session fixation mitigation — a fresh session ID is generated on first access.
    • User‑Agent binding — the request is terminated if the User‑Agent fingerprint changes during the session.
  • Prefer using sections (namespaces) for grouping related data (e.g., user, cart).

Configuration (application config, section SESSION):

  • session_save_path — Optional path where session files are stored. If set, session_save_path() is applied before session_start().
  • session_prefix — Optional string prefix for all session keys. Defaults to avro_ when empty.

Accessing the library:

// From controllers, models, addons, etc.
$s = $this->lib->session; // instance of session_lib

Constructor behavior​

Starts the session and prepares the environment.

  • Reads session_save_path (if non-empty) and calls session_save_path($path).
  • Calls session_start().
  • Reads session_prefix (defaults to avro_) and stores it internally as $this->sp.
  • Fixation protection on first use: calls regenerate() and sets [sp]_initiated flag.
  • User‑Agent binding: stores and checks [sp]_HTTP_USER_AGENT with a fingerprint; mismatch ends execution.

No parameters; created implicitly via $this->lib->session.

set_section()​

Set a whole section (namespace) with an associative array.

  • Parameters: array $data_arr, string $section
  • Returns: void

Usage:

$this->lib->session->set_section([
    'id' => 10,
    'name' => 'Alice',
], 'user');
// Stored under $_SESSION["{prefix}user"]

set()​

Set a value either at the top level or inside a section.

  • Parameters: string $item, mixed $value = '', string|null $section = null
  • Returns: void

Usage:

// Top-level key
$this->lib->session->set('token', 'abc123');

// Inside a section (namespace)
$this->lib->session->set('currency', 'USD', 'shop');

get()​

Get a value by key, optionally from a section.

  • Parameters: string $item, string|null $section = null
  • Returns: mixed — value if found; false if not found

Usage:

$token = $this->lib->session->get('token'); // string | false
$currency = $this->lib->session->get('currency', 'shop'); // string | false

get_section()​

Get the whole section array.

  • Parameters: string $section
  • Returns: array|false — section array if exists; false otherwise

Usage:

$user = $this->lib->session->get_section('user'); // array | false

remove_section()​

Remove (unset) a whole section.

  • Parameters: string $section
  • Returns: bool — true if removed; false if section didn’t exist

Usage:

$this->lib->session->remove_section('user');

remove()​

Remove a specific key or a whole section depending on parameters.

  • Parameters: string|null $item = null, string|null $section = null
  • Returns: bool — true on successful removal; false if nothing was removed

Behavior:

  • If $item === null and $section !== null: removes the whole section.
  • If $item !== null and $section !== null: removes $item from the given section.
  • If $item !== null and $section === null: removes the top‑level item.

Usage:

// Remove one value from a section
$this->lib->session->remove('currency', 'shop');

// Remove a whole section
$this->lib->session->remove(null, 'shop');

// Remove a top-level key
$this->lib->session->remove('token');

destroy()​

Destroy the current PHP session.

  • Parameters: none
  • Returns: void

Warning:

  • After calling destroy(), the current session_lib instance becomes unusable for the deleted session context. Create a new instance if you intend to start a new session later. If you only need to clear data and issue a fresh session ID, prefer regenerate().

Usage:

$this->lib->session->destroy();

regenerate()​

Clear all session data and generate a new session ID (mitigates fixation).

  • Parameters: none
  • Returns: void

Behavior:

  • Unsets all top‑level keys in $_SESSION.
  • Calls session_regenerate_id(true) to issue a new session ID.

Usage:

$this->lib->session->regenerate();

Practical example​

// Set up user info in a section
$this->lib->session->set_section([
    'id' => 42,
    'name' => 'Ada Lovelace',
], 'user');

// Update a single field in the same section
$this->lib->session->set('role', 'admin', 'user');

// Read values
$userId = $this->lib->session->get('id', 'user'); // 42
$user   = $this->lib->session->get_section('user'); // ['id'=>42, 'name'=>'Ada Lovelace', 'role'=>'admin']

// Remove one key
$this->lib->session->remove('role', 'user');

// Clear the whole section
$this->lib->session->remove_section('user');

// Start a fresh session (clears data + new ID)
$this->lib->session->regenerate();