PSR-16 simple cache drivers for PHP.
GitHub Action | Travis CI | Scrutinizer CI | Code Coverage | Code Quality |
---|---|---|---|---|
Caching, a common performance-boosting technique, is a staple feature in many frameworks and libraries. This interoperability allows libraries to utilize existing caching implementations rather than creating their own. PSR-6 has addressed this issue, but its formal and verbose nature complicates simple use cases. PSR-16 is a simpler approach seeks to create a streamlined standard interface for common situations, ensuring compatibility with PSR-6 in a straightforward manner.
Showcase
Simple Cache is utilized in Cache Master, a WordPress Cache Plugin, and it performs excellently. Check it out if you're running WordPress sites; it won't let you down.
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:
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.The following command displays a list of installed PHP modules.
php -m
Before using, make sure the required PHP modules are installed on your system.
(Non-PSR-16)
composer require shieldon/simple-cache
Cache
Class Cache
is an adapter that not only allows the implemented instance of Psr\SimpleCache\CacheInterface
, but also has built-in drivers already.
$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,
];
Those API methods are defined on Psr\SimpleCache\CacheInterface
. Please check out the PSR-16 document to get the detailed explanation.
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);
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"
}
*/
public function has(string $key): bool
Example:
if ($cache->has('foo3')) {
echo 'foo3 exists.';
} else {
echo 'foo3 does not exist.';
}
// foo3 exists.
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.
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);
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"
}
*/
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"
}
*/
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.
Non-PSR-16
public function clearExpiredItems(): array
This method returns a list of deleted 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"
}
*/
The data schema needs to be built for the initial use of MySQL and SQLite drivers.
This API can be utilized for this purpose.
$cache->rebuild();
Or build it manually.
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;
CREATE TABLE IF NOT EXISTS cache_data (
cache_key VARCHAR(40) PRIMARY KEY,
cache_value LONGTEXT
);
For built-in drivers, enabling garbage collection will automatically clear expired cache from your system.
Use the following parameters:
$config = [
'gc_enable' => true,
'gc_divisor' => 100, // default
'gc_probability' => 1, // default
];
This implies a 1% probability of executing garbage collection. Avoid setting it to 100% as it will unnecessarily fetch and check all keys one by one.
Example:
$driver = new \Shieldon\SimpleCache\Cache('file', [
'storage' => __DIR__ . '/../tmp',
'gc_enable' => true,
]);
You can just use the gc_enable
to enable garbage collection.
For the Redis, Memcache, and Memcached drivers, this method isn't necessary as expired items are automatically cleared.
Thank you for your interest in contributing to our project! We welcome contributions from everyone. Before getting started, please take a moment to review the guidelines below:
We utilize a Docker image that includes various dependencies for our code testing. The image is based on /tests/Fixture/docker/Dockerfile
and is preconfigured with the following components:
Follow the steps below to run the tests:
composer test:docker:build
composer test:docker:run
This PHP library was created for the 12th Ironman Game competition, hosted by ITHelp, a Taiwanese IT community. My chosen topic was "Road to PHP Master - The Best Practice in Open Source Code", composed in traditional Chinese. You can read it here if you're interested.
MIT