yiisoft/cache-file

Yii Caching Library - File Handler

3.1.0 2023-10-09 14:49 UTC

Requires

• php: ^8.0
• psr/simple-cache: ^2.0|^3.0

Requires (Dev)

• maglnet/composer-require-checker: ^4.4
• php-mock/php-mock-phpunit: ^2.6
• phpunit/phpunit: ^9.5
• rector/rector: ^0.18.3
• roave/infection-static-analysis-plugin: ^1.16
• spatie/phpunit-watcher: ^1.23
• vimeo/psalm: ^4.30|^5.6
• yiisoft/aliases: ^3.0
• yiisoft/di: ^1.2

Provides

• psr/simple-cache-implementation: 1.0.0

BSD-3-Clause

• framework
• file
• cache
• yii
• psr-16

README

Yii Cache Library - File Handler

This package implements file-based PSR-16 cache.

Requirements

• PHP 8.0 or higher.

Installation

The package could be installed with composer:

composer require yiisoft/cache-file

Configuration

When creating an instance of \Yiisoft\Cache\File\FileCache, you must specify the path to the base directory in which the cache files will be stored:

$cache = new \Yiisoft\Cache\File\FileCache('/path/to/directory');

Change the permission to be set for newly created directories:

$cache = new \Yiisoft\Cache\File\FileCache('/path/to/directory', 0777); // default is 0775

This value will be used by PHP chmod() function. No umask will be applied. Defaults to 0775, meaning the directory is read-writable by an owner and group, but read-only for other users.

Change the suffix of the cache files:

$cache = $cache->withFileSuffix('.txt'); // default is '.bin'

Change the permission to be set for newly created cache files:

$cache = $cache->withFileMode(0644); // default is null

This value will be used by PHP chmod() function. No umask will be applied. If not set, the permission will be determined by the current environment.

Change the level of sub-directories to store cache files:

$cache = $cache->withDirectoryLevel(3); // default is 1

If the system has huge number of cache files (e.g. one million), you may use a bigger value (usually no bigger than 3). Using sub-directories is mainly to ensure the file system is not over burdened with a single directory having too many files.

Change the probability of performing garbage collection when storing a piece of data in the cache:

$cache = $cache->withGcProbability(1000); // default is 10

The probability (parts per million) that garbage collection (GC) should be performed when storing a piece of data in the cache. Defaults to 10, meaning 0.001% chance. This number should be between 0 and 1000000. A value 0 means no GC will be performed at all.

General usage

The package does not contain any additional functionality for interacting with the cache, except those defined in the PSR-16 interface.

$cache = new \Yiisoft\Cache\File\FileCache('/path/to/directory');
$parameters = ['user_id' => 42];
$key = 'demo';

// try retrieving $data from cache
$data = $cache->get($key);

if ($data === null) {
    // $data is not found in cache, calculate it from scratch
    $data = calculateData($parameters);
    
    // store $data in cache for an hour so that it can be retrieved next time
    $cache->set($key, $data, 3600);
}

// $data is available here

In order to delete value you can use:

$cache->delete($key);
// Or all cache
$cache->clear();

To work with values in a more efficient manner, batch operations should be used:

• getMultiple()
• setMultiple()
• deleteMultiple()

This package can be used as a cache handler for the Yii Caching Library.

Testing

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework. To run it:

./vendor/bin/infection

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

Support the project

Follow updates

License

The Yii Cache Library - File Handler is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.