README

A drop-in replacement for PHP's default session handler which stores session data in a MySQL database, enhanced with optional Redis caching for high performance.

Overview

Zebra Session replaces PHP's default file-based session handling with a database-backed solution, improving performance, security, and scalability.

This version extends the original Zebra_Session by adding Redis as an optional cache layer, without breaking existing behavior.

MySQL = Source of Truth
Redis = Cache (optional)

✨ Features

MySQL-backed PHP sessions
Optional Redis caching
Protection against session hijacking & fixation
Session locking for concurrent AJAX requests
Flash session data
Garbage collection
Works with mysqli & PDO
Drop-in replacement

📦 Requirements

PHP 8.0+
MySQL 5.7+ / MariaDB
Redis 6+ (optional)
Composer
mysqli or PDO extension

📂 Project Structure

project-root/

│
├── install/
│   └── session_data.sql
├── vendor/
│   └── autoload.php
├── examples/
│    └── example.php
├── README.md
├── Zebra_Session.php

🗄️ Database Setup

Create Database

CREATE DATABASE zebra-session;

Create Session Table

Import install/session_data.sql or run:

CREATE TABLE `session_data` (
  `session_id` varchar(128) NOT NULL,
  `hash` varchar(32) NOT NULL,
  `session_data` longblob NOT NULL,
  `session_expire` int(11) NOT NULL,
  PRIMARY KEY (`session_id`),
  KEY `session_expire` (`session_expire`)
) ENGINE=InnoDB;

📥 Installation

Install via Composer

composer require stefangabos/zebra_session
composer require predis/predis

Manual Install

require 'path/to/Zebra_Session.php';

🚀 Basic Usage

$link = mysqli_connect('localhost', 'root', '', 'zebra-session');

require __DIR__ . '/vendor/autoload.php';
require 'Zebra_Session.php';

$session = new Zebra_Session(
    $link,
    'sEcUr1tY_c0dE',
    0,
    true,
    false,
    60,
    'session_data',
    false
);

session_start();

$_SESSION['foo'] = 'bar';

⚡ Redis Setup (Optional but Recommended)

Redis is used as a high-speed cache to reduce MySQL load. If Redis is unavailable, sessions automatically fall back to MySQL.

1️⃣ Install Redis Server

Ubuntu / Debian

sudo apt install redis-server
sudo systemctl enable redis
sudo systemctl start redis

Verify Redis:

redis-cli ping
# PONG

2️⃣ Install Redis PHP Client (Predis)

composer require predis/predis

3️⃣ Enable Redis in Zebra_Session

$session->enable_redis([
    'host' => '127.0.0.1',
    'port' => 6379,
    'username' => 'default',
    'password' => 'YOUR_PASSWORD',
    'ttl'  => 3600, // cache lifetime (seconds)
]);

4️⃣ How Redis Integration Works

Action Behavior

Session Read Redis → MySQL fallback Session Write MySQL + Redis Session Destroy MySQL + Redis Redis Down Safe fallback to MySQL

Session keys stored in Redis:

zebra_session:{session_id}

5️⃣ Debug: Check Session Source

echo $session->getLastSource();
// REDIS or MYSQL

🔐 Security

HttpOnly cookies
Secure cookies on HTTPS
Cookie-only sessions
Optional IP & User-Agent binding
MySQL session locking

Regenerate Session ID (IMPORTANT)

$session->regenerate_id();

Call this after login or privilege changes.

⚡ Flash Data

$session->set_flashdata('success', 'Profile updated!');

Available for one request only.

🧹 Destroy Session

$session->stop();

Deletes: - Session cookie - MySQL record - Redis cache

📊 Active Sessions

$count = $session->get_active_sessions();

📚 Original Documentation

Full API reference:\ https://stefangabos.github.io/Zebra_Session/Zebra_Session/Zebra_Session.html

📜 License

❤️ Credits

Zebra_Session -- Stefan Gabos
Predis -- Redis PHP Client

claytonpulman / zebra_session_plus

Maintainers

Details