README

异步缓存库

要求

• PHP 7.3
• Redis（如果需要使用Redis缓存提供程序）

此外，对于非阻塞上下文，以下事件库之一应该被安装

• ev
• event
• php-uv

安装

composer require harmonyio/cache

使用

此库既提供了与外部库协同工作以操作缓存的方法，也提供了直接与缓存接口的方式。

此库主要用于缓存感知库，在大多数情况下不应直接操作，因为这是一个底层库。

完整使用示例

<?php declare(strict_types=1);

namespace Foo;

use Amp\Dns;
use Amp\Dns\Record;
use Amp\Redis\Client;
use HarmonyIO\Cache\Item;
use HarmonyIO\Cache\Key;
use HarmonyIO\Cache\Provider\Redis;
use HarmonyIO\Cache\Ttl;
use function Amp\Dns\query;
use function Amp\wait;

require_once __DIR__ . '/path/to-autoload.php';

// create the cache storage connection
$cache = new Redis(new Client('tcp://127.0.0.1:6379'));

// create the key for the item to be stored
$key = new Key('DnsRequest', 'www.example.org', md5('www.example.org' . json_encode(['type' => 'A'])));

// get the data you want to cache (in this cache a DNS lookup)
$result = wait(query('www.example.org', Record::A));

// create the cacheable item to be stored in the cache for 1 hour
$itemToCache = new Item($key, json_encode($result), new Ttl(Ttl::ONE_HOUR));

// store the cached item
$cache->store($itemToCache);

// retrieve the item
var_dump($cache->get($key));

与缓存一起工作

缓存接口

缓存提供了4种方法与接口交互

<?php declare(strict_types=1);

namespace HarmonyIO\Cache;

use Amp\Promise;

interface Cache
{
    /**
     * @return Promise<null|string>
     */
    public function get(Key $key): Promise;

    /**
     * @return Promise<bool>
     */
    public function exists(Key $key): Promise;

    /**
     * @return Promise<null>
     */
    public function delete(Key $key): Promise;

    /**
     * @return Promise<bool>
     */
    public function store(Item $item): Promise;
}

可缓存项

要创建一个要存储在缓存中的项，请创建一个\HarmonyIO\Cache\Item.php实例

<?php declare(strict_types=1);

namespace Foo;

use HarmonyIO\Cache\Item;
use HarmonyIO\Cache\Key;
use HarmonyIO\Cache\Ttl;

$key = new Key('HttpRequest', 'https://httpbin.org/get', md5('https://httpbin.org/get'));

$itemToCache = new Item($key, 'Result from the http request', new Ttl(60));

上面的示例将创建一个要缓存的项（在这种情况下，来自http调用的模拟响应）并在缓存中存储60秒。

TTL

定义要缓存项的TTL主要有三种方式。

通过定义过期时间

<?php declare(strict_types=1);

namespace Foo;

use HarmonyIO\Cache\Ttl;

$ttl = Ttl::fromDateTime((new \DateTimeImmutable())->add(new \DateInterval('P1D')));

Ttl::fromDateTime期望一个\DateTimeInterface实例

通过定义TTL（秒）

<?php declare(strict_types=1);

namespace Foo;

use HarmonyIO\Cache\Ttl;

$ttl = new Ttl(10);

通过使用提供的常用TTL值常量定义TTL（秒）

<?php declare(strict_types=1);

namespace Foo;

use HarmonyIO\Cache\Ttl;

$ttl = new Ttl(Ttl::ONE_HOUR);

键

可缓存项使用的键由三部分组成

• 类型
• 源
• 哈希

类型

类型指的是存储的资源类型。常见用例包括：HttpRequest或DatabaseQuery。

类型用作在缓存中分组缓存项的方式，并提供了一种轻松地从缓存中清除整个组项的方法。

源代码

类型指的是资源的标识符。对于http请求，这通常是一个URL。或者对于数据库查询，这将是一个查询。

源用作在缓存中分组缓存项的方式，并提供了一种轻松地从缓存中清除整个组项的方法。

哈希

哈希必须是缓存中特定可缓存项的唯一标识符。例如，对于数据库查询，将来自预定义语句以及绑定参数的哈希值。

以下伪代码说明了有效哈希可能的样子

$hash = md5('SELECT * FROM users WHERE name = ?' . json_encode(['Bobby Tables']));

提供程序

目前，此库实现了两个缓存提供程序：Redis和InMemory。

Redis提供程序

建议使用的提供程序是Redis缓存提供程序：\HarmonyIO\Cache\Provider\Redis。要设置Redis提供程序，请注入具有正确Redis地址的Redis客户端

<?php declare(strict_types=1);

namespace Foo;

use Amp\Redis\Client;
use HarmonyIO\Cache\Provider\Redis;

$cache = new Redis(new Client('tcp://127.0.0.1:6379'));

InMemory（数组）提供程序

此库还提供了一个内存（简单的PHP数组）提供程序：\HarmonyIO\Cache\Provider\InMemory。这主要用于开发目的，可能不适合在生产环境中使用。
设置InMemory

<?php declare(strict_types=1);

namespace Foo;

use HarmonyIO\Cache\Provider\InMemory;

$cache = new InMemory();

\HarmonyIO\Cache\CacheableRequest和\HarmonyIO\Cache\CacheableResponse接口

此库提供了两个接口用于外部缓存感知库

• \HarmonyIO\Cache\CacheableRequest
• \HarmonyIO\Cache\CacheableResponse

\HarmonyIO\Cache\CacheableRequest

任何缓存感知库中可以执行的可缓存操作/资源都应该接受一个\HarmonyIO\Cache\CacheableRequest实例

<?php declare(strict_types=1);

namespace HarmonyIO\Cache;

interface CacheableRequest
{
    public function getCachingKey(): Key;

    public function getTtl(): Ttl;
}

此接口强制缓存请求必须同时具有键和TTL。

一个可缓存的请求示例可以在HttpClient包中找到：https://github.com/HarmonyIO/Http-Client/blob/56db13437e388b178c2d0b926f16a906aa48f9ae/src/Message/CachingRequest.php

请求以及最终的响应都会生成一个可缓存的项目，该项目可以存储在缓存中。

\HarmonyIO\Cache\CacheableResponse

在可缓存的库中可以执行的可缓存操作/资源应该生成一个\HarmonyIO\Cache\CacheableResponse的实例。

<?php declare(strict_types=1);

namespace HarmonyIO\Cache;

interface CacheableResponse extends \Serializable
{
}

这确保了可缓存操作/资源的响应可以被安全地存储在缓存中。

请求以及最终的响应都会生成一个可缓存的项目，该项目可以存储在缓存中。