README

Installation
Requirements

Scope

Caching of complex variables, and variables which are expensive to generate.
Like configuration, localization and service responses.

Not page caching, no stampede protection.

Cache abstraction

CacheBroker decouples code using cache from the actual PSR-16 cache implementation.

Defines three cache class aliases:

variable time-to-live (default ttl and set() arg ttl)
fixed time-to-live (default ttl, set() arg ttl ignored)
persistent (default ttl 'forever' and set() arg ttl ignored)

Plus three like the above which allow long keys; length 128 instead of the PSR-16 compliant 64.

How to use

Ask CacheBroker for an aliased type of cache instance - do not instantiate a particular cache class.

Extend CacheBroker, if you later want to switch from say file-based to database-based caching.

Dependency injection container ID: cache-broker

Recommendation: access (and thus instantiate) the cache broker via DI container ID 'cache-broker'.
See SimpleComplex Utils Dependency.

File-based caching

FileCache is a thorough and cautious PSR-16 Simple Cache implementation; file-based.
Coded defensively - key (and other argument) validation.

Addresses:

default time-to-live; ignore set() arg ttl option; no time-to-live
garbage collection
clearing all items or expired items only
exporting all items, to JSON
building/replacing a cache store during production (using a 'candidate' store)
CLI interface for clearing items, e.g. via cron
concurrency issues (storage-wise only)

Cache management, replacement and backup

Defines two extensions to the PSR-16 CacheInterface, implemented by FileCache.

ManageableCacheInterface

is the cache store new or empty?
setting default time-to-live; setting 'ignore' set() arg ttl
clearing and exporting
listing all cache stores

BackupCacheInterface

backup/restore
replacing a store, by building a 'candidate' and switching to that when it's complete

Example

// Bootstrap.
Dependency::genericSet('cache-broker', function () {
    return new \SimpleComplex\Cache\CacheBroker();
});
// ...
// Use.
/** @var \Psr\Container\ContainerInterface $container */
$container = Dependency::container();
/** @var \SimpleComplex\Cache\CacheBroker $cache_broker */
$cache_broker = $container->get('cache-broker');
/**
 * Create or re-initialize a cache store.
 *
 * @var \SimpleComplex\Cache\FileCache $cache_store
 */
$cache_store = $cache_broker->getStore(
    'some-cache-store',
    CacheBroker::CACHE_VARIABLE_TTL
);
unset($cache_broker);
/** @var mixed $whatever */
$whatever = $cache_store->get('some-key', 'the default value');

CLI commands

# List all cache commands and their help.
php cli.php cache -h
# One command's help.
php cli.php cache-xxx -h

# List existing cache stores.
php cli.php cache-list-stores

# Display/get value of a cache item.
php cli.php cache-get store key

# Delete a cache item.
php cli.php cache-delete store key

# Delete all expired items of one or all cache stores.
php cli.php cache-clear-expired

# Delete all items of one or all cache stores.
php cli.php cache-clear

# Backup a cache store.
php cli.php cache-backup store

# Restore a cache store from backup.
php cli.php cache-restore store

# Destroy one or all cache stores.
php cli.php cache-destroy

Installation

Create a 'private' files directory alongside the document root dir
and make it writable for the webserver user (www-data or apache).

Like:
/var/www/my-host/http
/var/www/my-host/private

On first cache store instantiation, FileCache will create directory
private/lib/simplecomplex/file-cache

If that directory structure isn't suitable, do either:

supply CacheBroker (or FileCache constructor directly) with a 'path' argument
extend FileCache and override it's class constant PATH_DEFAULT

Requirements

Suggestions

SimpleComplex Inspect

simplecomplex / cache

Maintainers

Details