<!--markup:2:end-->
$session->cf_secret = 'adyaiD9+255JeiskPybgisby';  // Secret for nonce generation
$session->cf_nonce_lifetime = 72;                 // Nonce expiration (seconds)
$session->cf_prevent_replay = 1;                    // Enable replay attack prevention

php<!--markup:1:end-->
<!--markup:2:begin-->		

<!--markup:2:end-->
$session->cf_cookie_prefix = '';                   // Prefix for all cookies
$session->cf_cookie_persistent = false;            // Make cookies persistent
$session->cf_cookie_lifetime = ;                  // Cookie lifetime ( = session cookie)
$session->cf_cookie_path = '/';                    // Cookie path
$session->cf_cookie_domain = '';                   // Cookie domain ('' = current host)
$session->cf_cookie_secure = false;                // HTTPS only
$session->cf_cookie_httponly = true;               // Disable JavaScript access
$session->cf_cookie_samesite = COOKIE_SAMESITE;   // SameSite attribute

php<!--markup:1:end-->
<!--markup:2:begin-->		

<!--markup:2:end-->
// Create a concrete session implementation
class MySession extends Session {
    // Implement abstract store_* methods
    // See "Implementation Guide" section
}

// Initialize and start session
$session = new MySession();
$session->cf_max_session = 36;  // 1 hour
$session->cf_cookie_path = '/';
$session->start('myapp');          // Session name: 'myapp'

// Store data
$session['user_id'] = 42;
$session['username'] = 'john';

// Retrieve data
echo $session['user_id'];  // 42

// Check if session is active
if ($session->active()) {
    echo "Session is active";
}

// Explicitly save and close
$session->write_close();

// Shutdown handler automatically called via register_shutdown_function()

// Array-like access (via ArrayObject)
$session['user_id'] = 123;
echo $session['user_id'];
unset($session['user_id']);
isset($session['user_id']);

// Convert to array
$all_data = $session->toArray();

php<!--markup:1:end-->

<!--markup:2:begin-->		

<!--markup:2:end-->
// Check if session is active
if ($session->active()) {
    // Session is running
}

// Get last state change message
$message = $session->message();  // 'replay', 'ip', 'ua', 'timeout', etc.

// Restart session (destroy old + start new)
$session->restart();

$session->regenerate_id($delete_old = false, $message = 'custom_reason');

// Example: Force regeneration on login
$session->start('myapp');
if ($user_authenticated) {
    $session->regenerate_id(false, 'login');
    $session['user_id'] = $user->id;
}

php<!--markup:1:end-->**
<!--markup:2:begin-->		

<!--markup:2:end-->
$session->cf_ip = $_SERVER['REMOTE_ADDR'];  // Set by HTTP class
// Validation happens automatically during start()

php<!--markup:1:end-->**
<!--markup:2:begin-->		

<!--markup:2:end-->
$session->cf_referer_check = 'example.com';
// Session rejected if HTTP_REFERER doesn't contain this string

php<!--markup:1:end-->**
<!--markup:2:begin-->		

<!--markup:2:end-->
$session->restart();
// New session created, old data cleared, sticky_ vars preserved

$sid = $session->id();  // "abc123xyz..."

php<!--markup:1:end-->

<!--markup:2:begin-->		

<!--markup:2:end-->
$data = $session->toArray();
foreach ($data as $key => $value) {
    echo "$key => $value\n";
}

$nonce = $session->create_nonce('form_submit', 36);
// Use in HTML: <input type="hidden" name="nonce" value="<?= $nonce ?>">

if ($nonce = $session->verify_nonce('form_submit', $_POST['nonce'])) {
    if ($nonce === -1) {
        // Possible replay, but might be legitimate AJAX
        $session->cf_prevent_replay = ;  // Disable for this request
    } else {
        // Safe to process
        process_form();
    }
}

// Session cookie
$session->setcookie('user_pref', 'dark_mode');

// Persistent cookie (3 days)
$session->setcookie('remember_me', 'token123', time() + 3*864);

// Delete cookie
$session->setcookie('old_cookie', null);

// Secure cookie with SameSite
$session->setcookie('token', 'abc123', time() + 36, 
    path: '/', secure: true, httponly: true, samesite: 'Strict');

php<!--markup:1:end-->

<!--markup:2:begin-->		

<!--markup:2:end-->
$session->delete_cookie('old_preference');

php<!--markup:1:end-->

<!--markup:2:begin-->		

<!--markup:2:end-->
protected function store_generate_id(): string {
    return hash('sha256', random_bytes(32));  // Your format
}

php<!--markup:1:end-->**
<!--markup:2:begin-->		

<!--markup:2:end-->
protected function store_open($name): void {
    $this->db = new PDO('sqlite::memory:');
}

php<!--markup:1:end-->**
<!--markup:2:begin-->		

<!--markup:2:end-->
protected function store_close(): void {
    // Close database, file, etc.
}

protected function store_gc(): void {
    $max_age = time() - $this->cf_gc_maxlifetime;
    // Delete files/records older than $max_age
}

┌─ Browser Request
│
├─ Application Code
│  └─ $session->start('appname')
│     │
│     ├─ Check if headers sent
│     ├─ Validate/read session name
│     ├─ Get session ID from:
│     │  1. Parameter $id
│     │  2. Cookie: {prefix}appname
│     ├─ Validate referer (if cf_referer_check set)
│     ├─ Validate ID format via store_validate_id()
│     ├─ store_open(name)
│     ├─ store_read(id)
│     │  └─ If missing/invalid/expired:
│     │     └─ set_new_id()
│     │        └─ regenerate_id = 2 (NEW)
│     ├─ Deserialize session data
│     ├─ exchangeArray(data)
│     ├─ active = true
│     ├─ cache_limiter()
│     │
│     └─ Security Checks (if NOT first request):
│        ├─ Verify NoReplay nonce
│        ├─ Check expiration flags
│        ├─ Check max session time
│        ├─ Check max idle time
│        ├─ Compare user agent (95%+ similarity)
│        ├─ Compare TLS status
│        ├─ Compare IP address
│        │  ├─ Match: OK
│        │  └─ Mismatch: destroy=1, regenerate
│        └─ Check regen time/probability
│           └─ regenerate_id()
│
├─ Application Code
│  └─ $session['key'] = 'value'
│
└─ End of Request
   │
   └─ register_shutdown_function() → terminator()
      │
      ├─ Process flash data
      │  └─ Decrement lifetimes
      │  └─ Remove expired flash
      ├─ write_session()
      │  └─ store_write(id, serialized_data)
      ├─ store_close()
      ├─ Probabilistic garbage collection
      │  └─ store_gc() (cf_gc_probability % chance)
      │     └─ Delete old sessions
      └─ Output sent to browser		

start() is called
├─ No ID in cookie
├─ store_read(id) → false
├─ set_new_id()
│  └─ id = store_generate_id()
│  └─ send_cookie(name, id)
├─ data = []
├─ active = true
├─ populate()
│  ├─ __started = now
│  ├─ __regenerated = now
│  ├─ __user_agent = UA
│  └─ sticky__created = now
└─ return true		

start() is called
├─ ID from cookie
├─ store_read(id) → serialized_data
├─ data = unserialize(data)
├─ exchangeArray(data)
├─ active = true
├─ Security checks:
│  ├─ Replay check
│  ├─ Timeout checks
│  ├─ UA/IP/TLS checks
│  └─ May trigger regenerate_id()
└─ return true		

regenerate_id($delete_old, $message) is called
├─ Check not headers_sent()
├─ Check $active
├─ Check not already regenerated in this request
├─ write_session()  [Save current data]
├─ set __expire:
│  ├─ if $delete_old=: __expire = now + 5
│  └─ if $delete_old>: __expire = 
├─ Generate new ID:
│  └─ loop:
│      ├─ id = store_generate_id()
│      └─ while store_read(id) !== false  [Ensure unique]
├─ Lock new session: store_read(id, true)
├─ Set: __regenerated = now
├─ Set: regenerated = 1
├─ Log event: sticky__log[] = [now, message]
└─ return true		

Triggered by:
├─ restart() → regenerate_id(true)
├─ Validation failure (destroy=2)
│  └─ regenerate_id(2)
│  └─ clean_vars()  [Remove non-sticky data]
└─ Timeout or security violation
Results in:
├─ __expire =   [Immediate expiration]
├─ Non-sticky variables cleared
├─ sticky_ variables preserved
└─ New session ID generated		

// Store flash message for next request
$session->set_flash('error', 'Username already exists', 1);  // 1 request
$session->set_flash('info', 'Welcome back!', 2);             // 2 requests

// In next request, data automatically available
echo $session['error'];  // "Username already exists"

==== Example: Protected Nonce (AJAX-Safe) ====

<!--markup:1:begin-->		

**Logged Events:**
  - Session regeneration (with reason)
  - Limited to 15 most recent events (old entries archived as '...')

----

=== Implementation Guide ===

==== Creating a Concrete Session Class ====

You must implement the abstract storage methods. Choose your storage backend: files, database, cache, etc.

===== File-Based Storage =====		

===== Database Storage (PDO) =====		

===== Redis Storage =====

<!--markup:1:begin-->		

==== Configuration Best Practices ====		

==== Testing Tips ====		

----

=== Security Checklist ===

Use this checklist when implementing sessions:
  - [ ] Use HTTPS only in production
  - [ ] Enable ##cf_cookie_secure##
  - [ ] Enable ##cf_cookie_httponly##
  - [ ] Set ##cf_cookie_samesite## to 'Strict' or 'Lax'
  - [ ] Set appropriate ##cf_max_session## timeout
  - [ ] Set appropriate ##cf_max_idle## timeout
  - [ ] Enable ##cf_prevent_replay##
  - [ ] Validate ##cf_ip## if possible
  - [ ] Validate ##cf_tls## on HTTPS sites
  - [ ] Use nonces for all state-changing forms
  - [ ] Implement proper logout (call ##restart()##)
  - [ ] Regenerate on privilege escalation (login)
  - [ ] Monitor ##sticky__ip## for suspicious changes
  - [ ] Review ##sticky__log## for attack patterns
  - [ ] Implement garbage collection (##store_gc##)
  - [ ] Hash session IDs before storing (see TODOs)
  - [ ] Use secure random token generation

----

=== Common Patterns ===

==== Login Flow ====

<!--markup:1:begin-->		

==== Permission Check with Session Regeneration ====		

==== Session Messages/Flash ====		

----

=== Performance Considerations ===

====Optimization Tips====
  1. **Minimize Session Writes:**
    - Session data only written during ##write_close()## or regeneration
    - No unnecessary serialization during reads
  2. **Garbage Collection:**
    - Probabilistic GC (based on ##cf_gc_probability##)
    - Only runs on ~2% of requests by default
    - Customize based on your session volume
  3. **Nonce Cleanup:**
    - Expired nonces automatically removed on verification
    - Verified nonces removed from storage
    - No manual cleanup needed
  4. **Session ID Validation:**
    - Regex-based validation is fast
    - No database lookup needed
  5. **Caching Strategy:**
    - Cache expensive lookups between session operations
    - Session data loaded once per request

==== Benchmarks ====

Typical performance on modern hardware:
  - Session start: ~1-5ms (file) / ~2-1ms (database)
  - Session write: <1ms (file) / 1-5ms (database)
  - Nonce generation: <1ms
  - Nonce verification: <1ms

----

=== Troubleshooting ===

==== Session Not Starting ====

<!--markup:1:begin-->		

==== Session ID Not Regenerating ====

<!--markup:1:begin-->