PSR-16 Simple Cache
| GitHub Action | Travis CI | Scrutinizer CI | Code Coverage | 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_socketis empty by default, accepting the absolute path of the unix domain socket file. If it is set,hostandportwill be ignored.
This command will show a list of the installed PHP modules.
php -mBefore 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
- Cache
- 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-cacheUsage
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): mixedExample:
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): boolExample:
if ($cache->has('foo3')) {
echo 'foo3 exists.';
} else {
echo 'foo3 does not exist.';
}
// foo3 exists.delete
public function delete(string $key): boolExample:
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): boolNote 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): iterableExample:
$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): boolExample:
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(): boolExample:
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(): arrayThis 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
- Terry L. from Tainan, Taiwan.
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