README

Yii Cache Library - File Handler

This package implements file-based PSR-16 cache.

Requirements

• PHP 8.1 - 8.5.

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');

Constructor parameters

You can configure the cache by passing parameters to the constructor:

$cache = new \Yiisoft\Cache\File\FileCache(
    cachePath: '/path/to/directory',
    directoryMode: 0777,        // Permission for new directories (default: 0775)
    fileSuffix: '.cache',       // Cache file suffix (default: '.bin')
    fileMode: 0644,             // Permission for new cache files (default: null)
    directoryLevel: 2,          // Sub-directory levels (default: 1)
    gcProbability: 100,         // GC probability in parts per million (default: 10)
);

Directory mode

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.

File suffix

Change the suffix of the cache files:

$cache = new \Yiisoft\Cache\File\FileCache(
    cachePath: '/path/to/directory',
    fileSuffix: '.cache', // default is '.bin'
);

File mode

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

$cache = new \Yiisoft\Cache\File\FileCache(
    cachePath: '/path/to/directory',
    fileMode: 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.

Directory level

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

$cache = new \Yiisoft\Cache\File\FileCache(
    cachePath: '/path/to/directory',
    directoryLevel: 2, // 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.

GC probability

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

$cache = new \Yiisoft\Cache\File\FileCache(
    cachePath: '/path/to/directory',
    gcProbability: 100, // 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.

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

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.

Support the project

Follow updates