Hypernic FileCache

FileCache is a lightweight file-based caching library for PHP 8+. It is designed to be fast, cross-platform, and safe with features such as default cache root in sys_get_temp_dir(), sharded directory structure based on sha1(key), TTL handled via filemtime(), atomic writes (LOCK_EX + rename()), conditional compression (gzencode/gzdecode), optional APCu support for hot values (with filesystem fallback), and a simple API (set, get, delete, flush, increment, decrement, replace).

Installation

Install with Composer:

composer require hypernic/filecache

Or copy FileCache.php directly into your project.

Usage Example

<?php
require __DIR__ . '/vendor/autoload.php';
use Hypernic\FileCache;

$cache = new FileCache();

// Store value for 60 seconds
$cache->set('my_key', 'hello world', 60);

// Retrieve
echo $cache->get('my_key'); // "hello world"

// Delete
$cache->delete('my_key');

// Counter demo
$cache->set('counter', 1, 3600);
$cache->increment('counter');   // 2
$cache->decrement('counter', 3); // -1

Configuration

Pass config options via constructor or with changeConfig():

$cache = new FileCache([
    'cacheDirectory'         => __DIR__ . '/cache/',
    'gzipCompression'        => true,
    'compressionThreshold'   => 2048,
    'unixLoadUpperThreshold' => 4.0,
    'useApcu'                => true,
    'apcuTtl'                => 30,
    'fileExtension'          => 'cache',
    'lazyDelete'             => true
]);

API

• set(string $key, mixed $value, int $expiry=0) → store a cache entry (0=10 years, >30 days=timestamp, else seconds).
• get(string $key) → retrieve value or false if missing/expired.
• delete(string $key) → delete one entry.
• flush() → clear all entries (keeps .keep files).
• increment(string $key, int $offset=1) → increment numeric value.
• decrement(string $key, int $offset=1) → decrement numeric value.
• replace(string $key, mixed $value, int $expiry=0) → replace only if entry exists.
• changeConfig(array $config) → update configuration.

Testing

Run PHPUnit tests:

./vendor/bin/phpunit --bootstrap vendor/autoload.php tests/test.php

Notes

• APCu is optional; if not installed, FileCache falls back to filesystem.
• Files named .keep inside cache directories are ignored by flush() so directories remain in version control.
• For maximum performance, place the cache directory on a tmpfs (Linux).