# 缓存驱动

CodeIgniter 封装了多种流行的快速动态缓存方式。除基于文件的缓存外，其他缓存方式都需要特定的服务器环境支持，若服务器环境不满足要求，将抛出致命异常。

## 使用示例

以下示例展示在控制器中的常见用法。

    <?php

    if (! $foo = cache('foo')) {
        echo 'Saving to the cache!<br>';
        $foo = 'foobarbaz!';

        // Save into the cache for 5 minutes
        cache()->save('foo', $foo, 300);
    }

    echo $foo;

可通过全局函数 `service()` 直接获取缓存引擎实例：

    <?php

    $cache = service('cache');

    $foo = $cache->get('foo');

## 配置缓存

缓存引擎的所有配置均在 app/Config/Cache.php 文件中完成。该文件包含以下配置项：

### $handler

指定启动缓存引擎时使用的首要处理器名称。 可用名称包括：apcu、dummy、file、memcached、redis、predis、wincache。

### $backupHandler

当首选 `$handler` 不可用时，将加载此备用缓存处理器。 通常使用 `File` 处理器，因为文件系统始终可用，但在复杂的多服务器环境中可能不适用。

### $prefix

当多个应用共用同一缓存存储时，可在此处添加自定义前缀字符串，该前缀将添加到所有键名之前。

### $ttl

未指定保存时间时的默认秒数。

警告：框架处理器未使用此配置（硬编码为 60 秒），但可能对项目和模块有用。未来版本将替换该硬编码值。

### $file

专用于 File 处理器的设置数组，用于确定缓存文件的保存方式。

### $memcached

使用 Memcached 处理器时的服务器数组。

### $redis

使用 Redis 和 Predis 处理器时的 Redis 服务器设置。

## 命令行工具

CodeIgniter 内置多个 命令，可从命令行辅助使用缓存。 这些工具不是使用缓存驱动的必需组件，但可能有所帮助。

### cache:clear

清除当前系统缓存：

    php spark cache:clear

### cache:info

显示当前系统的文件缓存信息：

    php spark cache:info

备注

此命令仅支持 File 缓存处理器。

## 类参考

class CodeIgniter\Cache\CacheInterface
  isSupported()
    返回:

      支持返回 `true`，不支持返回 `false`

    返回类型:

      `bool`

  get($key) → mixed
    参数:

      - $key (`string`) -- 缓存项名称

    返回:

      项值，未找到返回 `null`

    返回类型:

      `mixed`

    尝试从缓存存储中获取项。若项不存在，返回 null。

    示例：

        <?php

        $foo = $cache->get('my_cached_item');

  remember(string $key, int $ttl, Closure $callback)
    参数:

      - $key (`string`) -- 缓存项名称

      - $ttl (`int`) -- 存活时间（秒）

      - $callback (`Closure`) -- 缓存项返回 null 时调用的回调

    返回:

      缓存项的值

    返回类型:

      `mixed`

    从缓存获取项。若返回 `null`，将调用回调并保存结果。无论哪种情况，均返回值。

  save(string $key, $data[, int $ttl = 60])
    参数:

      - $key (`string`) -- 缓存项名称

      - $data (`mixed`) -- 要保存的数据

      - $ttl (`int`) -- 存活时间（秒，默认 60）

    返回:

      成功返回 `true`，失败返回 `false`

    返回类型:

      `bool`

    将项保存到缓存存储。保存失败返回 `false`。

    示例：

        <?php

        $cache->save('cache_item_id', 'data_to_cache');

  delete($key) → bool
    参数:

      - $key (`string`) -- 缓存项名称

    返回:

      成功返回 `true`，失败返回 `false`

    返回类型:

      `bool`

    从缓存存储删除指定项。删除失败返回 false。

    示例：

        <?php

        $cache->delete('cache_item_id');

  deleteMatching($pattern) → integer
    参数:

      - $pattern (`string`) -- 匹配缓存项键的 glob 风格模式

    返回:

      删除的项数

    返回类型:

      `integer`

    通过 glob 风格模式匹配键，从缓存存储批量删除多项。返回删除项的总数。

    重要

    此方法仅在 File、Redis 和 Predis 处理器中实现。 由于限制，无法在 Memcached 和 Wincache 处理器中实现。

    示例：

        <?php

        $cache->deleteMatching('prefix_*'); // deletes all items of which keys start with "prefix_"
        $cache->deleteMatching('*_suffix'); // deletes all items of which keys end with "_suffix"

    关于 glob 风格语法的更多信息，请参见 Glob (programming)。

  increment($key[, $offset = 1]) → mixed
    参数:

      - $key (`string`) -- 缓存 ID

      - $offset (`int`) -- 增加步长/值

    返回:

      成功返回新值，失败返回 `false`

    返回类型:

      `mixed`

    对原始存储值执行原子递增。

    示例：

        <?php

        // 'iterator' has a value of 2
        $cache->increment('iterator'); // 'iterator' is now 3
        $cache->increment('iterator', 3); // 'iterator' is now 6

  decrement($key[, $offset = 1]) → mixed
    参数:

      - $key (`string`) -- 缓存 ID

      - $offset (`int`) -- 减少步长/值

    返回:

      成功返回新值，失败返回 `false`

    返回类型:

      `mixed`

    对原始存储值执行原子递减。

    示例：

        <?php

        // 'iterator' has a value of 6
        $cache->decrement('iterator'); // 'iterator' is now 5
        $cache->decrement('iterator', 2); // 'iterator' is now 3

  clean()
    返回:

      成功返回 `true`，失败返回 `false`

    返回类型:

      `bool`

    "清理"整个缓存。缓存文件删除失败返回 false。

    示例：

        <?php

        $cache->clean();

  getCacheInfo()
    返回:

      整个缓存数据库的信息

    返回类型:

      `mixed`

    返回整个缓存的信息。

    示例：

        <?php

        var_dump($cache->getCacheInfo());

    备注

    返回的信息和数据结构取决于所使用的适配器。

  getMetadata(string $key)
    参数:

      - $key (`string`) -- 缓存项名称

    返回:

      缓存项的元数据。缺失项返回 `null`，或返回至少包含 "expire" 键（绝对 Unix 过期时间，永不过期则为 `null`）的数组。

    返回类型:

      `array|null`

    返回缓存中指定项的详细信息。

    示例：

        <?php

        var_dump($cache->getMetadata('my_cached_item'));

    备注

    返回的信息和数据结构取决于所使用的适配器。部分适配器（File、Memcached、Wincache） 对缺失项仍返回 `false`。

  static validateKey(string $key, string $prefix)
    参数:

      - $key (`string`) -- 候选缓存键

      - $prefix (`string`) -- 可选前缀

    返回:

      验证并添加前缀的键。若键超出驱动最大键长度，将进行哈希。

    返回类型:

      `string`

    处理器方法使用此方法验证键是否有效。非字符串、无效字符和空长度将抛出 `InvalidArgumentException`。

    示例：

        <?php

        use CodeIgniter\Cache\Handlers\BaseHandler;

        $prefixedKey = BaseHandler::validateKey($key, $prefix);

## 驱动

### APCu 缓存

APCu 是适用于 PHP 的内存键值存储。

使用此功能需安装 APCu PHP 扩展。

### 基于文件的缓存

需要缓存目录对应用可写。

谨慎使用，并确保对应用进行基准测试，因为磁盘 I/O 可能抵消缓存带来的性能提升。

### Memcached 缓存

Memcached 服务器可在缓存配置文件中指定。可用选项如下：

    <?php

    namespace Config;

    use CodeIgniter\Config\BaseConfig;

    class Cache extends BaseConfig
    {
        // ...

        public $memcached = [
            'host'   => '127.0.0.1',
            'port'   => 11211,
            'weight' => 1,
            'raw'    => false,
        ];

        // ...
    }

关于 Memcached 的更多信息，请参见 https://www.php.net/memcached。

### WinCache 缓存

在 Windows 下，也可使用 WinCache 驱动。

关于 WinCache 的更多信息，请参见 https://www.php.net/wincache。

### Redis 缓存

Redis 是一个内存键值存储，可在 LRU 缓存模式下运行。 使用需 Redis 服务器和 phpredis PHP 扩展。

连接 Redis 服务器的配置选项存储在缓存配置文件中。可用选项如下：

    <?php

    namespace Config;

    use CodeIgniter\Config\BaseConfig;

    class Cache extends BaseConfig
    {
        // ...

        public $redis = [
            'host'       => '127.0.0.1',
            'password'   => null,
            'port'       => 6379,
            'async'      => false, // specific to Predis and ignored by the native Redis extension
            'persistent' => false,
            'timeout'    => 0,
            'database'   => 0,
        ];

        // ...
    }

关于 Redis 的更多信息，请参见 https://redis.io。

### Predis 缓存

Predis 是一个灵活且功能完整的 Redis 键值存储 PHP 客户端库。 使用前需先在项目根目录执行：

    composer require predis/predis

关于 Redis 的更多信息，请参见 https://github.com/nrk/predis。

### Dummy 缓存

这是一个始终"未命中"的缓存后端。不存储任何数据， 但可以在不支持所选缓存的环境中保留缓存代码。