README

Yii Cache Library - DB Handler

This package implements database-based PSR-16 cache.

Supported databases

Packages	PHP	Versions	CI-Actions
[db-mssql]	8.1 - 8.5	2017 - 2025
[db-mysql] (MySQL)	8.1 - 8.5	5.7 - 9.5
[db-mysql] (MariaDB)	8.1 - 8.5	10.4 - 12.10
[db-oracle]	8.1 - 8.5	11C - 21C
[db-pgsql]	8.1 - 8.5	9.0 - 18.0
[db-sqlite]	8.1 - 8.5	3:latest

Requirements

• PHP 8.1 - 8.5.
• PDO PHP extension.

Installation

The package could be installed with Composer:

composer require yiisoft/cache-db

Create database connection

For more information see yiisoft/db.

Database Preparing

Package provides two way for preparing database:

1. Raw SQL. You can use it with the migration package used in your application.

   • Ensure tables:

     • MSSQL,
     • MySQL / MariaDB,
     • Oracle,
     • PostgreSQL
     • SQLite

   • Ensure no tables:

     • MSSQL,
     • MySQL / MariaDB,
     • Oracle,
     • PostgreSQL
     • SQLite

2. DbSchemaManager for ensureTable(), ensureNoTable() methods for cache table (by default {{%yii_cache}}).

// Create db schema manager
$dbSchemaManager = new DbSchemaManager($db);

// Ensure table with default name
$dbSchemaManager->ensureTable();

// Ensure table with custom name
$dbSchemaManager->ensureTable('{{%custom_cache_table}}');

// Ensure no table with default name
$dbSchemaManager->ensureNoTable();

// Ensure no table with custom name
$dbSchemaManager->ensureNoTable('{{%custom_cache_table}}');

Configuration

When creating an instance of \Yiisoft\Cache\Db\DbCache, you must pass an instance of the database connection.

$cache = new \Yiisoft\Cache\Db\DbCache($db, $table, $gcProbability);

• $db (\Yiisoft\Db\Connection\ConnectionInterface) - The database connection instance.
• $table (string) - The name of the database table to store the cache data. Defaults to "cache".
• $gcProbability (int) - The probability (parts per million) that garbage collection (GC) should be performed when storing a piece of data in the cache. Defaults to 100, meaning 0.01% chance. This number should be between 0 and 1000000. A value 0 meaning 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\Db\DbCache($db);
$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.

Additional logging

In order to log details about failures you may set a logger instance. It should be Psr\Log\LoggerInterface::class. For example, you can use yiisoft\Log:

$cache = new \Yiisoft\Cache\Db\DbCache($db, $table, $gcProbability);
$cache->setLogger(new \Yiisoft\Log\Logger());

This allows you to log cache operations, when ocurring errors, etc.

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 - DB 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