shieldon/simple-cache

PSR-16 simple cache drivers for PHP.

1.3.4 2023-07-14 06:36 UTC

Requires

• php: >=7.1.0
• psr/simple-cache: ^1.0

Requires (Dev)

• phpunit/phpunit: ^8

MIT

• Terry Lin

• psr-6
• psr-16
• php-cache

README

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.

Built-in drivers:

The required parameters are marked by an asterisk (*)

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.

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.

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 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"
    }
*/

Build Data Schema

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.

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, 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.

Note

For the Redis, Memcache, and Memcached drivers, this method isn't necessary as expired items are automatically cleared.

Contributing

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:

Guidelines

• Fork the repository and create your branch from master.
• Make sure your code follows our coding style and conventions.
• Keep your code concise, well-documented, and modular.
• Write clear commit messages that describe the purpose of your changes.
• Test your changes thoroughly to ensure they don't introduce any new issues.
• Make sure your code builds successfully without any errors or warnings.
• Update relevant documentation, including README files if necessary.
• Submit a pull request (PR) to the master branch of the original repository.

Code Testing

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:

• Redis
• MongoDB
• MySQL
• PHP
• Memcached
• APCu

Follow the steps below to run the tests:

• Make sure you have Docker installed on your machine. If not, you can download and install it from the official Docker website.
• Navigate to the project directory and build the Docker image by running the following command:

  composer test:docker:build
  

• Once the Docker image is built, you can run the tests by executing the following command:

  composer test:docker:run
  

• Observe the test results and make note of any failures or errors. The output will be displayed in the terminal.

Author

• Terry L. and contributers, such as Jimmy and others.

The Origin of this Library

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.

License

MIT