greg-md/php-cache

A powerful Cache for PHP.

dev-master 2019-07-24 08:58 UTC

Requires

• php: ^7.3
• ext-pdo: *
• ext-redis: *

Requires (Dev)

• phpunit/phpunit: ^8

MIT

• Grigorii Duca

• php
• cache
• php-cache
• greg-md
• greg-php
• web-artisans

README

A powerful Cache for PHP.

Table of Contents:

• Requirements
• Supported Drivers
• How It Works
• Cache Strategy
• License
• Huuuge Quote

Requirements

• PHP Version ^7.1

Supported Drivers

• Array - Use the PHP array as a storage;
• Tmp - Use temporary files as a storage. They are automatically removed when script ends;
• File - Use file based storage;
• Memcached - Use Memcached driver as a storage;
• Redis - Use Redis driver as a storage;
• Sqlite - Use Sqlite database as a storage.

How It Works

There are two ways of working with cache strategies. Directly or via a cache manager.

A cache manager could have many cache strategies and a default one. The cache manager implements the same cache strategy and could act as default one if it's defined.

In the next example we will use a cache manager.

First of all, you have to initialize a cache manager and register some strategies:

$manager = new \Greg\Cache\CacheManager();

// Register a file cache
$manager->registerStrategy('store1', new \Greg\Cache\FileCache(__DIR__ . '/storage'));

// Register a sqlite cache
$manager->register('store2', function() {
    $pdo = new \PDO('sqlite:' . __DIR__ . '/storage/store2.sqlite');

    return new \Greg\Cache\SqliteCache($pdo);
});

// Register a redis cache
$manager->register('store3', function() {
    $redis = new \Redis();

    $redis->connect('127.0.0.1');

    return new \Greg\Cache\RedisCache($redis);
});

Optionally, you can define a default store to be used by the cache manager.

$manager->setDefaultStoreName('store2');

Then, you can set or get some data:

// Add some data in "store1"
$manager->store('store1')->set('foo', 'FOO');

// Add some data in default store, which is "store2"
$manager->set('bar', 'BAR');

// Get "bar" value from default store.
$value = $manager->get('bar'); // result: BAR

Cache Strategy

If you want, you can create your own strategies. They should implement the \Greg\Cache\CacheStrategy interface.

Below you can find a list of supported methods.

• has - Determines whether an item is present in the cache;
• hasMultiple - Determines whether multiple items are present in the cache;
• get - Fetch a value from the cache;
• getMultiple - Obtains multiple cache items by their unique keys;
• set - Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time;
• setMultiple - Persists a set of key => value pairs in the cache, with an optional TTL;
• forever - Persists forever data in the cache, uniquely referenced by a key;
• foreverMultiple - Persists forever a set of key => value pairs in the cache;
• delete - Delete an item from the cache by its unique key;
• deleteMultiple - Delete multiple items from the cache by their unique keys;
• clear - Clear the storage;
• remember - Sometimes you may wish to retrieve an item from the cache, but also store a default value if the requested item doesn't exist;
• increment - Increment a value;
• decrement - Decrement a value;
• incrementFloat - Increment a float value;
• decrementFloat - Decrement a float value;
• touch - Set a new expiration on an item;
• pull - Retrieve and delete an item from the cache;
• add - Persists data in the cache if it's not present.

has

Determines whether an item is present in the cache.

has(string $key): bool

$key - The cache item key.

Example:

$strategy->has('foo');

hasMultiple

Determines whether an item is present in the cache.

hasMultiple(array $keys): bool

$keys - The cache items keys.

Example:

$strategy->hasMultiple(['foo', 'bar']);

get

Fetch a value from the cache.

get(string $key, mixed $default = null): mixed

$key - The unique key of this item in the cache;
$default - Default value to return if the key does not exist.

Return the value of the item from the cache, or $default in case of cache miss.

Example:

$strategy->get('foo');

getMultiple

Obtains multiple cache items by their unique keys.

getMultiple(array $keys, $default = null): mixed

$keys - A list of keys that can obtained in a single operation;
$default - Default value to return for keys that do not exist.

Return a list of key => value pairs. Cache keys that do not exist or are stale will have $default as value.

Example:

$strategy->get('foo');

set

Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.

set(string $key, $value, ?int $ttl = null): $this

$key - The key of the item to store;
$value - The value of the item to store, must be serializable;
$ttl - Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Example:

$strategy->set('foo', 'FOO');

setMultiple

Persists a set of key => value pairs in the cache, with an optional TTL.

setMultiple(array $values, ?int $ttl = null): $this

$values - A list of key => value pairs for a multiple-set operation;
$ttl - Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Example:

$strategy->setMultiple(['foo' => 'FOO', 'bar' => 'BAR']);

forever

Persists forever data in the cache, uniquely referenced by a key.

forever(string $key, $value): $this

$key - The key of the item to store;
$value - The value of the item to store, must be serializable.

Example:

$strategy->forever('foo', 'FOO');

// or

$strategy->set('foo', 'FOO', 0);

foreverMultiple

Persists forever a set of key => value pairs in the cache.

foreverMultiple(array $values): $this

$values - A list of key => value pairs for a multiple-set operation.

Example:

$strategy->foreverMultiple(['foo' => 'FOO', 'bar' => 'BAR']);

// or

$strategy->setMultiple(['foo' => 'FOO', 'bar' => 'BAR'], 0);

delete

Delete an item from the cache by its unique key.

delete(string $key): $this

$key - The unique cache key of the item to delete.

Example:

$strategy->delete('foo');

deleteMultiple

Delete multiple items from the cache by their unique keys.

deleteMultiple(array $keys): $this

$keys - The unique cache keys of the items to delete.

Example:

$strategy->deleteMultiple(['foo', 'bar']);

clear

Wipes clean the entire cache's keys.

clear(): $this

Example:

$strategy->clear();

remember

Sometimes you may wish to retrieve an item from the cache, but also store a default value if the requested item doesn't exist.

remember(string $key, callable($this): mixed $callable, ?int $ttl = null): mixed

$key - The unique key of this item in the cache;
$callable - The value callable of the item to store when the key is not present in the cache. The value must be serializable;
$ttl - Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Example:

$strategy->remember('foo', function() {
    return 'FOO';
});

increment

Increment a value.

increment(string $key, int $amount = 1, ?int $ttl = null): $this

$key - The unique key of this item in the cache;
$abount - The amount to increment;
$ttl - Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Example:

$strategy->increment('foo');

$strategy->increment('foo', 10);

decrement

Decrement a value.

decrement(string $key, int $amount = 1, ?int $ttl = null): $this

$key - The unique key of this item in the cache;
$abount - The amount to decrement;
$ttl - Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Example:

$strategy->decrement('foo');

$strategy->decrement('foo', 10);

incrementFloat

Increment a float value.

incrementFloat(string $key, float $amount = 1.0, ?int $ttl = null): $this

$key - The unique key of this item in the cache;
$abount - The amount to increment;
$ttl - Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Example:

$strategy->incrementFloat('foo');

$strategy->incrementFloat('foo', 1.5);

decrementFloat

Decrement a float value.

decrementFloat(string $key, float $amount = 1.0, ?int $ttl = null): $this

$key - The unique key of this item in the cache;
$abount - The amount to decrement;
$ttl - Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Example:

$strategy->decrementFloat('foo');

$strategy->decrementFloat('foo', 1.5);

touch

Set a new expiration on an item.

touch(string $key, ?int $ttl = null): $this

$key - The unique key of this item in the cache;
$ttl - Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Example:

$strategy->touch('foo', 100);

pull

Retrieve and delete an item from the cache.

pull(string $key, $default = null): mixed

$key - The unique key of this item in the cache;
$default - Default value to return for keys that do not exist.

Return the value of the item from the cache, or $default in case of cache miss.

Example:

$strategy->pull('foo'); // return foo value

$strategy->pull('foo'); // return null

add

Persists data in the cache if it's not present.

add(string $key, $value, ?int $ttl = null): $this

$key - The key of the item to store;
$value - The value of the item to store, must be serializable;
$ttl - Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Return true if the item is actually added to the cache. Otherwise, return false.

Example:

$strategy->add('foo', 'FOO'); // return true

$strategy->add('foo', 'FOO2'); // return false

License

MIT © Grigorii Duca

Huuuge Quote