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
{
}

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

请求以及最终的响应都将产生一个可缓存的项，该项可以被存储在缓存中。