Home

InitPHP Cache — Wiki

Welcome to the official documentation for initphp/cache — a small, PSR-16 (Simple Cache) caching library for PHP 8.0+ with interchangeable handlers for the filesystem, PDO databases, Redis, Memcache(d) and WinCache.

composer require initphp/cache

use InitPHP\Cache\Cache;
use InitPHP\Cache\Handler\File;

$cache = Cache::create(File::class, ['path' => __DIR__ . '/var/cache']);

$cache->set('user:42', ['name' => 'Jane'], 3600); // store for 1 hour
$cache->get('user:42');                            // ['name' => 'Jane']
$cache->get('missing', 'default');                 // "default"
$cache->has('user:42');                            // true
$cache->delete('user:42');                         // true

One factory call picks the backend; the API is identical for every handler, so you can develop against the File handler and switch to Redis in production by changing a single line.

The package in one table

Symbol	Role
Cache	Static factory — builds and configures a handler. The usual entry point.
CacheInterface	The contract every handler fulfils; extends Psr\SimpleCache\CacheInterface.
BaseHandler	Abstract base with the shared behaviour; extend it to write your own handler.
Handler\File · Handler\PDO · Handler\Redis · Handler\Memcache · Handler\Wincache	The five built-in handlers.
CacheException / InvalidArgumentException	The two exception types; both implement the matching PSR-16 interface.

Start here

• New to the package? Read Installation, then Quick Start.
• Choosing a backend? Compare the handlers and their configuration options.
• Want the precise rules for keys, TTLs and values? Keys, TTL & Values.
• Building counters? Counters explains increment() / decrement().
• Looking for a specific method? The full API Reference lists every public member.
• Writing your own backend? Custom Handlers.

The handlers at a glance

Handler	Class	Backend	Needs	Best for
File	Handler\File	Filesystem	core only	local dev, small/medium caches
PDO	Handler\PDO	SQL (MySQL, SQLite, PostgreSQL…)	ext-pdo	shared DB, no extra service
Redis	Handler\Redis	Redis	ext-redis	hot, distributed caches
Memcache(d)	Handler\Memcache	Memcached	ext-memcached / ext-memcache	distributed, ephemeral caches
WinCache	Handler\Wincache	WinCache user cache	ext-wincache	deprecated — legacy Windows only

What you get

• One PSR-16 API, five backends. Every handler implements CacheInterface, so your code never depends on the concrete handler.
• Exact value fidelity. Anything serialize() accepts round-trips exactly — including null, false, arrays and objects. See Keys, TTL & Values.
• Flexible TTLs. null (forever), an integer of seconds, or a DateInterval; a zero/negative TTL deletes the item.
• Consistent counters. increment() / decrement() behave identically on every backend and return the new value. See Counters.
• Strict, predictable keys. PSR-16 key validation with the reserved set {}()/\@:. See Keys, TTL & Values.
• PSR-16 exceptions. Every error implements Psr\SimpleCache\CacheException, so one catch covers the library. See Error Handling.
• Extensible. Add your own backend by extending BaseHandler.

At a glance — behaviour

You call	You get
set('k', $v)	stores $v with no expiry → true
set('k', $v, 60)	stores $v for 60 seconds → true
set('k', $v, new DateInterval('PT5M'))	stores $v for 5 minutes → true
set('k', $v, 0) (or negative)	deletes k → true
get('missing')	null
get('missing', 'x')	"x" (returned as-is, never invoked)
get('k') after storing null	null (use has() to detect the miss)
increment('n', 5) on a missing key	5 (new value)
get('bad:key')	throws InvalidArgumentException (: is reserved)

Package metadata

• License: MIT
• Minimum PHP: 8.0
• Runtime dependencies: psr/simple-cache ^3.0
• Required extensions: none for the File handler; one per backend otherwise
• Packagist: initphp/cache
• Source: github.com/InitPHP/Cache
• Issues: github.com/InitPHP/Cache/issues
• Discussions: github.com/orgs/InitPHP/discussions

If something in this wiki is unclear, wrong, or out of date, open an issue — documentation fixes are merged eagerly.