缓存

Testing Is Documentation

tests/Cache/CacheTest.php缓存 - 图1

QueryPHP 为系统提供了灵活的缓存功能，提供了多种缓存驱动。

内置支持的缓存类型包括 file、redis，未来可能增加其他驱动。

使用方式

使用容器 caches 服务

  1. \App::make('caches')->set(string $name, $data, ?int $expire = null): void;
  2. \App::make('caches')->get(string $name, $defaults = false, ?int $expire = null);

依赖注入

  1. class Demo
  2. {
  3.     private \Leevel\Cache\Manager $cache;
  5.     public function __construct(\Leevel\Cache\Manager $cache)
  6.     {
  7.         $this->cache = $cache;
  8.     }
  9. }

使用静态代理

  1. \Leevel\Cache\Proxy\Cache::set(string $name, $data, ?int $expire = null): void;
  2. \Leevel\Cache\Proxy\Cache::get(string $name, $defaults = false, ?int $expire = null);

缓存配置

系统的缓存配置位于应用下面的 option/cache.php 文件。

可以定义多个缓存连接，并且支持切换，每一个连接支持驱动设置。

  1. <?php
  3. declare(strict_types=1);
  5. /*
  6.  * This file is part of the your app package.
  7.  *
  8.  * The PHP Application For Code Poem For You.
  9.  * (c) 2018-2099 http://yourdomian.com All rights reserved.
  10.  *
  11.  * For the full copyright and license information, please view the LICENSE
  12.  * file that was distributed with this source code.
  13.  */
  15. return [
  16.     /*
  17.      * ---------------------------------------------------------------
  18.      * 默认缓存驱动
  19.      * ---------------------------------------------------------------
  20.      *
  21.      * 这里可以可以设置为 file、memcache 等
  22.      * 系统为所有缓存提供了统一的接口，在使用上拥有一致性
  23.      */
  24.     'default' => Leevel::env('CACHE_DRIVER', 'file'),
  26.     /*
  27.      * ---------------------------------------------------------------
  28.      * 程序默认缓存时间
  29.      * ---------------------------------------------------------------
  30.      *
  31.      * 设置好缓存时间，超过这个时间系统缓存会重新进行获取, 小与等于 0 表示永不过期
  32.      * 缓存时间为当前时间加上以秒为单位的数量
  33.      */
  34.     'expire' => (int) Leevel::env('CACHE_EXPIRE', 86400),
  36.     /*
  37.      * ---------------------------------------------------------------
  38.      * 缓存时间预置
  39.      * ---------------------------------------------------------------
  40.      *
  41.      * 为了满足不同的需求，有部分缓存键值需要的缓存时间不一致，有些缓存可能需要频繁更新
  42.      * 于是这里我们可以通过配置缓存预设时间来控制缓存的键值的特殊时间，其中 * 表示通配符
  43.      * 键值 = 缓存值，键值不带前缀,例如 ['option' => 60]
  44.      */
  45.     'time_preset' => [],
  47.     /*
  48.      * ---------------------------------------------------------------
  49.      * 缓存连接参数
  50.      * ---------------------------------------------------------------
  51.      *
  52.      * 这里为所有的缓存的连接参数，每一种不同的驱动拥有不同的配置
  53.      * 虽然有不同的驱动，但是在缓存使用上却有着一致性
  54.      */
  55.     'connect' => [
  56.         'file' => [
  57.             // driver
  58.             'driver' => 'file',
  60.             // 文件缓存路径
  61.             'path' => Leevel::runtimePath('file'),
  63.             // 默认过期时间
  64.             'expire' => null,
  65.         ],
  67.         'redis' => [
  68.             // driver
  69.             'driver' => 'redis',
  71.             // 默认缓存服务器
  72.             'host' => Leevel::env('CACHE_REDIS_HOST', '127.0.0.1'),
  74.             // 默认缓存服务器端口
  75.             'port' => (int) Leevel::env('CACHE_REDIS_PORT', 6379),
  77.             // 认证密码
  78.             'password' => Leevel::env('CACHE_REDIS_PASSWORD', ''),
  80.             // redis 数据库索引
  81.             'select' => 0,
  83.             // 超时设置
  84.             'timeout' => 0,
  86.             // 是否使用持久连接
  87.             'persistent' => false,
  89.             // 默认过期时间
  90.             'expire' => null,
  91.         ],
  93.         'redisPool' => [
  94.             // driver
  95.             'driver' => 'redisPool',
  97.             // redis 连接
  98.             'redis_connect' => 'redis',
  100.             // 最小空闲连接池数据量
  101.             'max_idle_connections' => (int) Leevel::env('CACHE_REDIS_POOL_MAX_IDLE_CONNECTIONS', 30),
  103.             // 最大空闲连接池数据量
  104.             'min_idle_connections' => (int) Leevel::env('CACHE_REDIS_POOL_MIN_IDLE_CONNECTIONS', 10),
  106.             // 通道写入最大超时时间设置(单位为毫秒)
  107.             'max_push_timeout' => -1000,
  109.             // 通道获取最大等待超时(单位为毫秒)
  110.             'max_pop_timeout' => 0,
  112.             // 连接的存活时间(单位为毫秒)
  113.             'keep_alive_duration' => 60000,
  115.             // 最大尝试次数
  116.             'retry_times' => 3,
  117.         ],
  119.         'file_throttler' => [
  120.             // driver
  121.             'driver' => 'file',
  123.             // 文件缓存路径
  124.             'path' => Leevel::runtimePath('throttler'),
  126.             // 默认过期时间
  127.             'expire' => null,
  128.         ],
  130.         'redis_throttler' => [
  131.             // driver
  132.             'driver' => 'redis',
  134.             // 默认缓存服务器
  135.             'host' => Leevel::env('THROTTLER_REDIS_HOST', '127.0.0.1'),
  137.             // 默认缓存服务器端口
  138.             'port' => (int) Leevel::env('THROTTLER_REDIS_PORT', 6379),
  140.             // 认证密码
  141.             'password' => Leevel::env('THROTTLER_REDIS_PASSWORD', ''),
  143.             // redis 数据库索引
  144.             'select' => 0,
  146.             // 超时设置
  147.             'timeout' => 0,
  149.             // 是否使用持久连接
  150.             'persistent' => false,
  152.             // 默认过期时间
  153.             'expire' => null,
  154.         ],
  156.         'file_session' => [
  157.             // driver
  158.             'driver' => 'file',
  160.             // 文件缓存路径
  161.             'path' => Leevel::runtimePath('session'),
  163.             // 默认过期时间
  164.             'expire' => null,
  165.         ],
  167.         'redis_session' => [
  168.             // driver
  169.             'driver' => 'redis',
  171.             // 默认缓存服务器
  172.             'host' => Leevel::env('SESSION_REDIS_HOST', '127.0.0.1'),
  174.             // 默认缓存服务器端口
  175.             'port' => (int) Leevel::env('SESSION_REDIS_PORT', 6379),
  177.             // 认证密码
  178.             'password' => Leevel::env('SESSION_REDIS_PASSWORD', ''),
  180.             // redis 数据库索引
  181.             'select' => 0,
  183.             // 超时设置
  184.             'timeout' => 0,
  186.             // 是否使用持久连接
  187.             'persistent' => false,
  189.             // 默认过期时间
  190.             'expire' => null,
  191.         ],
  192.     ],
  193. ];

缓存参数根据不同的连接会有所区别，通用的缓存参数如下：

配置项配置描述
expire设置好缓存时间（小与等于 0 表示永不过期，单位时间为秒）
time_preset缓存时间预置

Uses

  1. <?php
  3. use Leevel\Cache\File;
  4. use Leevel\Filesystem\Helper;

缓存基本使用

设置缓存

  1. # Leevel\Cache\ICache::set
  2. /**
  3.  * 设置缓存.
  4.  *
  5.  * @param mixed $data
  6.  */
  7. public function set(string $name, $data, ?int $expire = null): void;

缓存配置 $option 根据不同缓存驱动支持不同的一些配置。

file 驱动

配置项配置描述
expire设置好缓存时间（小与等于 0 表示永不过期，单位时间为秒）
time_preset缓存时间预置
path缓存路径

redis 驱动

配置项配置描述
expire设置好缓存时间（小与等于 0 表示永不过期，单位时间为秒）
time_preset缓存时间预置

获取缓存

  1. # Leevel\Cache\ICache::get
  2. /**
  3.  * 获取缓存.
  4.  *
  5.  * @param mixed $defaults
  6.  *
  7.  * @return mixed
  8.  */
  9. public function get(string $name, $defaults = false);

缓存不存在或者过期返回 false，可以根据这个判断缓存是否可用。

删除缓存

  1. # Leevel\Cache\ICache::delete
  2. /**
  3.  * 清除缓存.
  4.  */
  5. public function delete(string $name): void;

直接指定缓存 key 即可，无返回。

  1. public function testBaseUse(): void
  2. {
  3.     $filePath = __DIR__.'/cache/hello.php';
  4.     $cache = new File([
  5.         'path' => __DIR__.'/cache',
  6.     ]);
  8.     $cache->set('hello', 'world');
  9.     $this->assertTrue(is_file($filePath));
  10.     $this->assertSame('world', $cache->get('hello'));
  12.     $cache->delete('hello');
  13.     $this->assertFalse(is_file($filePath));
  14.     $this->assertFalse($cache->get('hello'));
  15. }

put 批量设置缓存

函数签名

  1. # Leevel\Cache\ICache::put
  2. /**
  3.  * 批量设置缓存.
  4.  *
  5.  * @param array|string $keys
  6.  * @param mixed        $value
  7.  */
  8. public function put($keys, $value = null, ?int $expire = null): void;

TIP

缓存配置 $expire 和 set 的用法一致。

  1. public function testPut(): void
  2. {
  3.     $cache = new File([
  4.         'path' => __DIR__.'/cache',
  5.     ]);
  7.     $cache->put('hello', 'world');
  8.     $cache->put(['hello2' => 'world', 'foo' => 'bar']);
  10.     $this->assertSame('world', $cache->get('hello'));
  11.     $this->assertSame('world', $cache->get('hello2'));
  12.     $this->assertSame('bar', $cache->get('foo'));
  14.     $cache->delete('hello');
  15.     $cache->delete('hello2');
  16.     $cache->delete('foo');
  18.     $this->assertFalse($cache->get('hello'));
  19.     $this->assertFalse($cache->get('hello2'));
  20.     $this->assertFalse($cache->get('foo'));
  21. }

set 值 false 不允许作为缓存值

因为 false 会作为判断缓存是否存在的一个依据，所以 false 不能够作为缓存，否则会引起缓存穿透。

  1. public function testSetNotAllowedFalse(): void
  2. {
  3.     $this->expectException(\InvalidArgumentException::class);
  4.     $this->expectExceptionMessage(
  5.         'Data `false` not allowed to avoid cache penetration.'
  6.     );
  8.     $cache = new File([
  9.         'path' => __DIR__.'/cache',
  10.     ]);
  12.     $cache->set('hello', false);
  13. }

put 批量设置缓存支持过期时间

  1. public function testPutWithExpire(): void
  2. {
  3.     $cache = new File([
  4.         'path' => __DIR__.'/cache',
  5.     ]);
  7.     $filePath = __DIR__.'/cache/hello.php';
  9.     $cache->put('hello', 'world', 33);
  10.     $cache->put(['hello2' => 'world', 'foo' => 'bar'], 22);
  12.     $this->assertSame('world', $cache->get('hello'));
  13.     $this->assertSame('world', $cache->get('hello2'));
  14.     $this->assertSame('bar', $cache->get('foo'));
  15.     $this->assertTrue(is_file($filePath));
  16.     $this->assertStringContainsString('[33,', file_get_contents($filePath));
  18.     $cache->delete('hello');
  19.     $cache->delete('hello2');
  20.     $cache->delete('foo');
  22.     $this->assertFalse($cache->get('hello'));
  23.     $this->assertFalse($cache->get('hello2'));
  24.     $this->assertFalse($cache->get('foo'));
  25. }

remember 缓存存在读取否则重新设置

缓存值为闭包返回，闭包的参数为缓存的 key。

函数签名

  1. # Leevel\Cache\ICache::remember
  2. /**
  3.  * 缓存存在读取否则重新设置.
  4.  *
  5.  * @return mixed
  6.  */
  7. public function remember(string $name, Closure $dataGenerator, ?int $expire = null);

TIP

缓存配置 $expire 和 set 的用法一致。

  1. public function testRemember(): void
  2. {
  3.     $cache = new File([
  4.         'path' => __DIR__.'/cache',
  5.     ]);
  6.     $filePath = __DIR__.'/cache/hello.php';
  8.     $this->assertFalse(is_file($filePath));
  9.     $this->assertSame(['hello' => 'world'], $cache->remember('hello', function (string $key) {
  10.         return [$key => 'world'];
  11.     }));
  12.     $this->assertTrue(is_file($filePath));
  13.     $this->assertSame(['hello' => 'world'], $cache->get('hello'));
  15.     $cache->delete('hello');
  17.     $this->assertFalse($cache->get('hello'));
  18.     $this->assertFalse(is_file($filePath));
  19. }

remember 缓存存在读取否则重新设置支持过期时间

  1. public function testRememberWithExpire(): void
  2. {
  3.     $cache = new File([
  4.         'path' => __DIR__.'/cache',
  5.     ]);
  7.     $filePath = __DIR__.'/cache/hello.php';
  8.     if (is_file($filePath)) {
  9.         unlink($filePath);
  10.     }
  12.     $this->assertFalse(is_file($filePath));
  13.     $this->assertSame('123456', $cache->remember('hello', function (string $key) {
  14.         return '123456';
  15.     }, 33));
  17.     $this->assertTrue(is_file($filePath));
  18.     $this->assertSame('123456', $cache->remember('hello', function (string $key) {
  19.         return '123456';
  20.     }, 4));
  21.     $this->assertSame('123456', $cache->get('hello'));
  23.     $cache->delete('hello');
  25.     $this->assertFalse($cache->get('hello'));
  26.     $this->assertFalse(is_file($filePath));
  27. }

has 缓存是否存在

  1. public function testHas(): void
  2. {
  3.     $cache = new File([
  4.         'path' => __DIR__.'/cache',
  5.     ]);
  6.     $filePath = __DIR__.'/cache/has.php';
  8.     $this->assertFalse($cache->has('has'));
  9.     $cache->set('has', 'world');
  10.     $this->assertTrue(is_file($filePath));
  11.     $this->assertTrue($cache->has('has'));
  12. }

increase 自增

  1. public function testIncrease(): void
  2. {
  3.     $cache = new File([
  4.         'path' => __DIR__.'/cache',
  5.     ]);
  6.     $filePath = __DIR__.'/cache/increase.php';
  8.     $this->assertSame(1, $cache->increase('increase'));
  9.     $this->assertTrue(is_file($filePath));
  10.     $this->assertSame(101, $cache->increase('increase', 100));
  11. }

decrease 自减

  1. public function testDecrease(): void
  2. {
  3.     $cache = new File([
  4.         'path' => __DIR__.'/cache',
  5.     ]);
  6.     $filePath = __DIR__.'/cache/decrease.php';
  8.     $this->assertSame(-1, $cache->decrease('decrease'));
  9.     $this->assertTrue(is_file($filePath));
  10.     $this->assertSame(-101, $cache->decrease('decrease', 100));
  11. }

ttl 获取缓存剩余时间

剩余时间存在 3 种情况。

  • 不存在的 key:-2
  • key 存在，但没有设置剩余生存时间:-1
  • 有剩余生存时间的 key:剩余时间
  1. public function testTtl(): void
  2. {
  3.     $cache = new File([
  4.         'path' => __DIR__.'/cache',
  5.     ]);
  6.     $filePath = __DIR__.'/cache/ttl.php';
  8.     $this->assertFalse($cache->has('ttl'));
  9.     $this->assertSame(-2, $cache->ttl('ttl'));
  10.     $cache->set('ttl', 'world');
  11.     $this->assertTrue(is_file($filePath));
  12.     $this->assertSame(86400, $cache->ttl('ttl'));
  13.     $cache->set('ttl', 'world', 1);
  14.     $this->assertSame(1, $cache->ttl('ttl'));
  15.     $cache->set('ttl', 'world', 0);
  16.     $this->assertSame(-1, $cache->ttl('ttl'));
  17. }

缓存时间预置

不同场景下面的缓存可能支持不同的时间，我们可以在配置中预设时间而不是在使用时通过第三个参数传递 expire 过期时间，这种做法非常灵活。

缓存时间预设支持 * 通配符，可以灵活控制一类缓存时间。

  1. public function testCacheTime(): void
  2. {
  3.     $file = new File([
  4.         'time_preset' => [
  5.             'foo'         => 500,
  6.             'bar'         => -10,
  7.             'hello*world' => 10,
  8.             'foo*bar'     => -10,
  9.         ],
  10.         'path' => __DIR__.'/cache',
  11.     ]);
  13.     $file->set('foo', 'bar');
  14.     $file->set('bar', 'hello');
  15.     $file->set('hello123456world', 'helloworld1');
  16.     $file->set('hello789world', 'helloworld2');
  17.     $file->set('foo123456bar', 'foobar1');
  18.     $file->set('foo789bar', 'foobar2');
  19.     $file->set('haha', 'what about others?');
  21.     $this->assertSame('bar', $file->get('foo'));
  22.     $this->assertSame('hello', $file->get('bar'));
  23.     $this->assertSame('helloworld1', $file->get('hello123456world'));
  24.     $this->assertSame('helloworld2', $file->get('hello789world'));
  25.     $this->assertSame('foobar1', $file->get('foo123456bar'));
  26.     $this->assertSame('foobar2', $file->get('foo789bar'));
  27.     $this->assertSame('what about others?', $file->get('haha'));
  29.     $file->delete('foo');
  30.     $file->delete('bar');
  31.     $file->delete('hello123456world');
  32.     $file->delete('hello789world');
  33.     $file->delete('foo123456bar');
  34.     $file->delete('foo789bar');
  35.     $file->delete('haha');
  36. }

TIP

缓存时间预设小与等于 0 表示永不过期，单位时间为秒。

键值命名规范

缓存键值默认支持正则 /^[A-Za-z0-9\-\_:.]+$/，可以通过 setKeyRegex 修改。

  1. public function testInvalidCacheKey(): void
  2. {
  3.     $this->expectException(\InvalidArgumentException::class);
  4.     $this->expectExceptionMessage('Cache key must be `/^[A-Za-z0-9\-\_:.]+$/`.');
  6.     $cache = new File([
  7.         'path' => __DIR__.'/cache',
  8.     ]);
  9.     $cache->set('hello+world', 1);
  10. }

setKeyRegex 设置缓存键值正则

缓存键值默认支持正则 /^[A-Za-z0-9\-\_:.]+$/，可以通过 setKeyRegex 修改。

  1. public function testSetKeyRegex(): void
  2. {
  3.     $cache = new File([
  4.         'path' => __DIR__.'/cache',
  5.     ]);
  6.     $cache->setKeyRegex('/^[a-z+]+$/');
  7.     $cache->set('hello+world', 1);
  8.     $this->assertSame(1, $cache->get('hello+world'));
  9. }