README

BinaryStorage is a lightweight binary key/value store for PHP. It keeps all values inside a single data file and all keys inside a binary index, reducing filesystem overhead and allowing fast random-access lookups.

It is designed for projects that need simple, fast persistent storage without running Redis, SQLite, or a full database.

BinaryStorage is a fast, lightweight, zero-dependency binary key/value store for PHP (one data file, one index file).

✔️ Why use BinaryStorage?

BinaryStorage may be useful if you want:

• A simple file-based storage (no server to run, no extensions)
• Fast lookup by key
• Efficient prefix search (startsWith) and substring search (contains)
• Low disk usage (one data file + one index file)
• Automatic cleanup via file compaction
• The ability to store any PHP value (array, scalar, object → via serialize)

It is not a replacement for a database, but fits well for caches, catalogs, and read-heavy workloads.

📦 Installation

composer require olivier-ls/binary-storage-php

🚀 Basic Usage

use OlivierLS\BinaryStorage\BinaryStorage;

$store = new BinaryStorage(__DIR__ . '/data');

// Open (or create) a storage
$store->open('products');

// Write values
$store->set('products', 'product_123', [
    'name'  => 'MacBook Pro',
    'price' => 2499.99,
    'stock' => 42
]);

$store->set('products', 'product_456', ['name' => 'iPhone']);
$store->set('products', 'product_789', ['name' => 'iPad']);

// Save index
$store->saveIndex('products');

// Read a value
$product = $store->get('products', 'product_123');

// Prefix search
$list = $store->startsWith('products', 'product_');

// Substring search
$list = $store->contains('products', ['pad']);

// Compact the data file (optional)
$stats = $store->compact('products');

// Stats
print_r($store->stats('products'));

// Close
$store->close('products');

📘 API Overview

• $ttl (optional) – Time-to-live in seconds. If provided, the entry will expire automatically after this time.

🧰 When to use it

Good scenarios:

• Large product lists or catalog caching
• Simple local persistent storage
• High-volume read access
• CLI tools needing a lightweight storage
• Storing precomputed data
• Replacing many small JSON files

Less good scenarios:

• Heavy concurrent writes
• Complex queries
• Replacing a real database

🤝 Contributing

Issues and pull requests are welcome. If you find a performance bottleneck or have an idea for improved index structures, feel free to open a discussion.

📄 License

MIT