shieldon/simple-cache

PSR-16 simple cache drivers for PHP.

1.3.1 2020-11-12 11:56 UTC

This package is auto-updated.

Last update: 2021-09-24 03:23:49 UTC


README

GitHub Action Travis CI Scrutinizer CI Code Coverage Code Quality
build Build Status Build Status codecov Scrutinizer Code Quality

PSR-16 simple cache drivers for PHP.

Showcase

Simple Cache is used in Cache Master, a WordPress Cache Plugin, and works great. Check it out if you are running WordPress sites, it will not let you down.

Built-in drivers:

The required parameters are marked by an asterisk (*)

Driver name ($driver) PHP modules ($config)
File file - *storage
Redis redis redis host, port, user, pass, unix_socket
MongoDB mongo mongodb host, port, user, pass, dbname, collection, unix_socket
MySQL mysql pdo_mysql host, port, *user, *pass, *dbname, table, charset
SQLite sqlite pdo_sqlite *storage
APC apc apc -
APCu apcu apcu -
Memcache memcache memcache host, port, unix_socket
LibMemcached memcached memcached host, port, unix_socket
WinCache wincache wincache -

Note:

  • WinCache is excluded from unit testing since it's only used on Windows, and the testing processes are done on Linux environment.
  • unix_socket is empty by default, accepting the absolute path of the unix domain socket file. If it is set, host and port will be ignored.

This command will show a list of the installed PHP modules.

php -m

Before you use, make sure you have the required PHP modules installed on the system.

Table of Contents

  • Install
  • Usage
    • Cache
      • Built-in drivers
      • __construct
      • $driver
      • $config
  • API
    • set
    • get
    • has
    • delete
    • getMultiple
    • setMultiple
    • deleteMultiple
    • clear
    • clearExpiredItems (Non-PSR-16)
  • Build Data Schema
    • MySQL
    • SQLite
  • Garbage Collection
  • Author
  • License

Install

composer require shieldon/simple-cache

Usage

Cache

Class Cache is an adapter that not only allows the implemented instance of Psr\SimpleCache\CacheInterface, but also has built-in drivers already.

__construct($driver = '', $config = [])

Create a cache handler using the file driver.

Example:

$driver = new \Shieldon\SimpleCache\Cache('file', [
    'storage' => __DIR__ . '/../tmp'
]);

$driver

(string|CacheInterface)

The class name of a built-in driver, or a PSR-16 driver that implements Psr\SimpleCache\CacheInterface.

$config

(array)

An array of parameters will be passed to a built-in driver.

Example:

Redis

$config = [
    'host' => '127.0.0.1',
    'port' => 6379,
    'user' => null,
    'pass' => null,
];

File

$config = [
    'storage' => '/tmp/simple-cache',
];

Mysql

$config = [
    'host'    => '127.0.0.1',
    'port'    => 3306,
    'user'    => null,
    'pass'    => null,
    'dbname'  => null,
    'table'   => 'cache_data',
    'charset' => 'utf8'
];

Sqlite

$config = [
    'storage' => '/tmp/simple-cache',
];

Mongo

$config = [
    'host'       => '127.0.0.1',
    'port'       => 27017,
    'user'       => null,
    'pass'       => null,
    'database'   => 'test',
    'collection' => 'cache_data',
];

Memcache, Memcached

$config = [
    'host' => '127.0.0.1',
    'port' => 11211,
];

API

Those API methods are defined on Psr\SimpleCache\CacheInterface. Please check out the PSR-16 document to get the detailed explanation.

  • set
  • get
  • has
  • delete
  • setMultiple
  • getMultiple
  • deleteMultiple
  • clear
  • clearExpiredItems (Non-PSR-16)

set

public function set(string $key, mixed value, $ttl = null);

Note that $ttl accepts null,int,DateInterval. The null means that the key never expires until deleted.

Example:

$cache->set('foo', 'bar', 300);
$cache->set('foo2', 'bar2');

$array = [
    'hello' => 'world',
    'yes' => 'Taiwan',
];

$cache->set('foo3', $array);
$cache->set('foo4', $array, 300);

get

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

Example:

echo $cache->get('foo', 'placeholder');
// bar

sleep(301);

echo $cache->get('foo', 'placeholder');
// placeholder

echo $cache->get('foo');
// null

echo $cache->get('foo2', 'placeholder');
// bar2

$example = $cache->get('foo3', 'placeholder');
var_dump($example);
// string(11) "placeholder"

$example = $cache->get('foo4', 'placeholder');
var_dump($example);
/* 
    array(2) {
    ["hello"]=>
    string(5) "world"
    ["yes"]=>
    string(6) "Taiwan"
    }
*/

has

public function has(string $key): bool

Example:

if ($cache->has('foo3')) {
    echo 'foo3 exists.';
} else {
    echo 'foo3 does not exist.';
}
// foo3 exists.

delete

public function delete(string $key): bool

Example:

if ($cache->delete('foo3')) {
    echo 'foo3 has been deleted successfully.';
} else {
    echo 'Failed to delete key foo3.';
}
// foo3 has been deleted successfully.

if ($cache->has('foo3')) {
    echo 'foo3 exists.';
} else {
    echo 'foo3 does not exist.';
}
// foo3 does not exist.

setMultiple

public function setMultiple(iterable $values, $ttl = null): bool

Note that $ttl accepts null,int,DateInterval. The null means that the key never expires until deleted.

Example:

$array = [
    'bar' => 'foo',
    'bar2' => 'foo2',
];

$cache->setMultiple($array, 300);

getMultiple

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

Example:

$example = $cache->getMultiple(['bar', 'bar2', 'bar3'], 'hello');
var_dump($example);
/* 
    array(3) {
    ["bar"]=>
    string(3) "foo"
    ["bar2"]=>
    string(4) "foo2"
    ["bar3"]=>
    string(5) "hello"
    }
*/

deleteMultiple

public function deleteMultiple(array $keys): bool

Example:

if ($cache->deleteMultiple(['bar', 'bar2'])) {
    echo 'bar and bar2 have been deleted successfully.';
} else {
    echo 'Failed to delete keys bar or bar2.';
}
// bar and bar2 have been deleted successfully.

$example = $cache->getMultiple(['bar', 'bar2', 'bar3'], 'hello');
var_dump($example);
/* 
    array(3) {
    ["bar"]=>
    string(5) "hello"
    ["bar2"]=>
    string(5) "hello"
    ["bar3"]=>
    string(5) "hello"
    }
*/

clear

public function clear(): bool

Example:

if ($cache->clear()) {
    echo 'All cached data has been deleted successfully.';
} else {
    echo 'Failed to delete the cached data.';
}
// All cached data has been deleted successfully.

clearExpiredItems Non-PSR-16

public function clearExpiredItems(): array

This method will return a list of the removed cache keys.

Note: Redis and Memcache, Memcached drivers will always return an empty array. See Garbage Collection section below.

Example:

$cache->set('foo', 'bar', 300);
$cache->set('foo2', 'bar2', 5);
$cache->set('foo3', 'bar3', 5);

sleep(6);

$expiredItems = $cache->clearExpiredItems();
var_dump($expiredItems);

/* 
    array(2) {
    [0]=>
    string(4) "foo2"
    [1]=>
    string(4) "foo3"
    }
*/

Build Data Schema

For the first time of the use of the MySQL and SQLite drivers, the data schema is needed to build.

You can use this API to make it.

$cache->rebuild();

Or build it manually.

MySQL

CREATE TABLE IF NOT EXISTS `cache_data` (
    `cache_key` varchar(40) NOT NULL,
    `cache_value` longtext,
    PRIMARY KEY (`cache_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

SQLite

CREATE TABLE IF NOT EXISTS cache_data (
    cache_key VARCHAR(40) PRIMARY KEY,
    cache_value LONGTEXT
);

Garbage Collection

For built-in drivers, you can enable the garbage collection to clear expired cache from your system automatically.

Use those parameters:

$config = [
    'gc_enable'      => true,
    'gc_divisor'     => 100, // default
    'gc_probability' => 1, // default
];

It means there will be a 1% chance of performing the garbage collection. Do not use it as 100% chance because it will fetch all keys and check them one by one, totally unnecessary.

Example:

$driver = new \Shieldon\SimpleCache\Cache('file', [
    'storage'   => __DIR__ . '/../tmp',
    'gc_enable' => true,
]);

You can just use the gc_enable to enable garbage collection.

Note

For Redis and Memcache, Memcached drivers, there is no need to use this method because the expired items will be cleared automatically.

Author

The story about this library

This PHP library was born for the 12th Ironman Game contest hosted by ITHelp, an IT community in Taiwan. I named my topic "Road to PHP Master - The Best Practice in Open Souce Code.", written in traditional Chinese. Read here, if you're interested.

License

MIT