Primordyx Framework Documentation

SessionSecurity
in package

Class SessionSecurity

Secure session configuration for the Primordyx framework. Provides comprehensive session security hardening with HTTPS detection, browser fingerprinting, session regeneration, and hijacking protection.

This class should be called early in the request lifecycle (typically in bootstrap) to establish secure session defaults before any other session operations.

SECURITY FEATURES:

  • Forces cookie-only sessions (blocks URL-based session IDs)
  • Enables strict mode to reject invalid session IDs
  • Configures HTTPS-only cookies when available
  • Prevents JavaScript access to session cookies (XSS protection)
  • Implements SameSite=Strict for CSRF protection
  • Custom session storage outside web root
  • Browser fingerprinting for session validation
  • Automatic session regeneration every 30 minutes
  • Session hijacking detection and recovery
  • Configurable session lifetime and storage paths

Usage: // Basic usage with required storage path SessionSecurity::configure([ 'storage_path' => '/app/storage/sessions' ]);

// Full custom configuration SessionSecurity::configure([ 'storage_path' => '/custom/sessions', // REQUIRED 'lifetime' => 7200, // 2 hours 'cookie_name' => '__Host-MyApp', // Custom cookie name 'gc_probability' => 2, // 2% cleanup chance 'regenerate_interval' => 1800 // 30 minutes ]);

Tags
since
2.0.0

Table of Contents

Properties

$configured  : bool
$cookieName  : string
$gcDivisor  : int
$gcProbability  : int
$isHttps  : bool
$lifetime  : int
$regenerateInterval  : int
$storagePath  : string|null

Methods

__wakeup()  : mixed
configure()  : bool
Configure and initialize secure session settings.
cookieName()  : string
Get or set session cookie name.
gcProbability()  : int
Get or set garbage collection probability (1-100).
generateBrowserFingerprint()  : string
Generate browser fingerprint for session validation.
isConfigured()  : bool
Get current configuration status.
lifetime()  : int
Get or set session lifetime in seconds.
storagePath()  : string|null
Get or set session storage path.
autoDetectStoragePath()  : string
Auto-detect appropriate session storage path.
configurePhpSession()  : bool
Configure PHP session settings for security.
configureSessionCookie()  : void
Configure session cookie parameters.
configureStorageDirectory()  : bool
Configure and create session storage directory.
isPathSuitable()  : bool
Check if a path is suitable for session storage.
startSecureSession()  : bool
Start session with security validation and fingerprinting.
__clone()  : mixed
__construct()  : mixed

Properties

$configured

protected static bool $configured = false

Whether configuration has been applied

$cookieName

protected static string $cookieName = '__Host-AppAuth'

Default secure cookie name

$gcDivisor

protected static int $gcDivisor = 100

Garbage collection divisor

$gcProbability

protected static int $gcProbability = 1

Garbage collection probability (1%)

$isHttps

protected static bool $isHttps = null

Whether HTTPS is detected

$lifetime

protected static int $lifetime = 3600

Default session lifetime in seconds (1 hour)

$regenerateInterval

protected static int $regenerateInterval = 1800

Session regeneration interval in seconds (30 minutes)

$storagePath

protected static string|null $storagePath = null

Storage path - must be explicitly set

Methods

configure()

Configure and initialize secure session settings.

public static configure([array<string|int, mixed> $options = [] ]) : bool

This method applies comprehensive session security configuration and starts the session with browser fingerprinting and hijacking protection. Should be called once early in the application lifecycle.

IMPORTANT: storage_path is REQUIRED and must be explicitly provided. The path should be outside your web root for security.

Configuration Options:

  • storage_path: REQUIRED - Absolute path for session storage (e.g., '/app/storage/sessions')
  • lifetime: Session lifetime in seconds (default: 3600 = 1 hour)
  • cookie_name: Session cookie name (default: __Host-AppAuth)
  • gc_probability: Cleanup probability 1-100 (default: 1)
  • gc_divisor: Cleanup divisor (default: 100, so 1/100 = 1%)
  • regenerate_interval: Regeneration interval in seconds (default: 1800 = 30 min)
Parameters
$options : array<string|int, mixed> = []

Configuration options - storage_path is required

Return values
bool —

True if configuration was successful

cookieName()

Get or set session cookie name.

public static cookieName([string|null $newName = null ]) : string
Parameters
$newName : string|null = null

New cookie name to set, or null to get current

Return values
string —

Previous cookie name value

gcProbability()

Get or set garbage collection probability (1-100).

public static gcProbability([int|null $newProbability = null ]) : int
Parameters
$newProbability : int|null = null

New probability to set, or null to get current

Return values
int —

Previous probability value

generateBrowserFingerprint()

Generate browser fingerprint for session validation.

public static generateBrowserFingerprint() : string

Creates a hash based on stable browser characteristics to detect session hijacking attempts. Only uses headers that are consistent across requests but unique enough to identify browser differences.

Return values
string —

SHA-256 hash of browser characteristics

isConfigured()

Get current configuration status.

public static isConfigured() : bool
Return values
bool —

True if configure() has been called successfully

lifetime()

Get or set session lifetime in seconds.

public static lifetime([int|null $newLifetime = null ]) : int
Parameters
$newLifetime : int|null = null

New lifetime to set, or null to get current

Return values
int —

Previous lifetime value

storagePath()

Get or set session storage path.

public static storagePath([string|null $newPath = null ]) : string|null
Parameters
$newPath : string|null = null

New storage path to set, or null to get current

Return values
string|null —

Previous storage path value

autoDetectStoragePath()

Auto-detect appropriate session storage path.

protected static autoDetectStoragePath() : string

Attempts to find a suitable directory outside the web root for storing session files. Falls back to system temp directory if no suitable path found.

Return values
string —

Absolute path to session storage directory

configurePhpSession()

Configure PHP session settings for security.

protected static configurePhpSession() : bool
Return values
bool —

True if configuration was successful

configureSessionCookie()

Configure session cookie parameters.

protected static configureSessionCookie() : void

configureStorageDirectory()

Configure and create session storage directory.

protected static configureStorageDirectory() : bool
Return values
bool —

True if directory configuration was successful

isPathSuitable()

Check if a path is suitable for session storage.

protected static isPathSuitable(string $path) : bool
Parameters
$path : string

Path to check

Return values
bool —

True if path can be used or created

startSecureSession()

Start session with security validation and fingerprinting.

protected static startSecureSession() : bool
Return values
bool —

True if session started successfully


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results