README

从 https://github.com/OmnilogSage/DynamoDbCachePsr6 分支出来，以使用 AWS Async DynamoDb。

用于在 DynamoDB 中存储缓存并实现 PSR-6 和 PSR-16 接口的库。还可以查看该库的 Symfony 扩展包。

安装

composer require omnilog/psr6-dynamo-db

使用方法

使用方法非常简单，您只需在构造函数中定义详细信息，然后像使用任何其他 PSR-6 或 PSR-16 实现一样使用它

<?php

use Omnilog\DynamoDbCache\DynamoDbCache;
use Omnilog\DynamoDbCache\DynamoDbCacheBuilder;
use AsyncAws\DynamoDb\DynamoDbClient;

$cache = new DynamoDbCache('dynamoTableName', new DynamoDbClient([]));

// with custom field names
$cache = new DynamoDbCache('dynamoTableName', new DynamoDbClient([]), 'customPrimaryKeyField', 'customTtlField', 'customValueField');

// using builder
$cache = DynamoDbCacheBuilder::create('dynamoTableName', new DynamoDbClient([]))
    ->withPrimaryField('customPrimaryKeyField')
    ->withTtlField('customTtlField')
    ->withValueField('customValueField')
    ->build();

建议使用构建器来创建新实例。构建器是不可变的，每个方法都返回一个新实例。

字段的默认值如下

• 主键 - id (字符串)
• ttl 字段 - ttl (数字)
• 值字段 - value (字符串)

在使用此库之前，您必须创建 DynamoDB 表。

基本示例

<?php
use AsyncAws\DynamoDb\DynamoDbClient;
use Omnilog\DynamoDbCache\DynamoDbCache;

function get(string $key): string
{
    $dynamoDbClient = new DynamoDbClient([
        'region' => 'eu-central-1',
        'version' => 'latest'
    ]);
    $cache = new DynamoDbCache('cache', $dynamoDbClient); // the default field names are used - id, ttl and value
    
    $item = $cache->getItem($key);
    if ($item->isHit()) {
        return $item->get();    
    }

    // do something to fetch the item
    $result = '...';

    $item->set($result);
    $item->expiresAfter(3600); // expire after one hour
    if (!$cache->save($item)) {
        throw new RuntimeException('Could not save cache');
    }

    return $result;
}

使用 PSR-16 接口的示例

<?php

use AsyncAws\DynamoDb\DynamoDbClient;
use Omnilog\DynamoDbCache\DynamoDbCache;

function get(string $key): string
{
    $dynamoDbClient = new DynamoDbClient([
        'region' => 'eu-central-1',
        'version' => 'latest'
    ]);
    $cache = new DynamoDbCache('cache', $dynamoDbClient); // the default field names are used - id, ttl and value

    $value = $cache->get($key);
    if ($value !== null) {
        return $value;
    }
    
    // do something to fetch the item
    $result = '...';

    if (!$cache->set($key, $result, 3600)) {
       throw new RuntimeException('Could not save cache');     
    }
    
    return $result;
}

前缀

您可以使用前缀配置自动为 DynamoDB 中的所有键添加前缀，如下所示

<?php

use Omnilog\DynamoDbCache\DynamoDbCacheBuilder;
use AsyncAws\DynamoDb\DynamoDbClient;

$cache = DynamoDbCacheBuilder::create('myTable', new DynamoDbClient([]))
    ->withPrefix('myCustomPrefix#')
    ->build();

$item = $cache->getItem('key1'); // fetches an item with key myCustomPrefix#key1
$key = $item->getKey(); // $key holds the full key including prefix, myCustomPrefix#key1

转换器

此实现支持所有 \Psr\Cache\CacheItemInterface 实例，使用转换器将对象转换为 \Omnilog\DynamoDbCache\DynamoCacheItem。请注意，转换过程中可能会丢失一些信息，特别是过期日期。

您可以编写自己的转换器以支持您的特定类，包括过期日期支持，如下所示

<?php

use Omnilog\DynamoDbCache\Converter\CacheItemConverterInterface;
use Psr\Cache\CacheItemInterface;
use Omnilog\DynamoDbCache\DynamoCacheItem;
use Omnilog\DynamoDbCache\Encoder\SerializeItemEncoder;

class MyCacheItemConverter implements CacheItemConverterInterface
{
    /**
     * If this methods returns true, the converter will be used
     */
    public function supports(CacheItemInterface $cacheItem): bool
    {
        return $cacheItem instanceof MyCacheItem;
    }
    
    public function convert(CacheItemInterface $cacheItem): DynamoCacheItem
    {
        assert($cacheItem instanceof MyCacheItem);
        return new DynamoCacheItem(
            $cacheItem->getKey(),
            $cacheItem->isHit(),
            $cacheItem->get(),
            $cacheItem->getExpirationDate(), // this is a custom method from the hypothetical MyCacheItem
            new SerializeItemEncoder()
        );
    }
}

然后您需要将其注册到转换器并将其分配给缓存

<?php

use Omnilog\DynamoDbCache\Converter\CacheItemConverterRegistry;
use Omnilog\DynamoDbCache\DynamoDbCache;
use AsyncAws\DynamoDb\DynamoDbClient;
use Omnilog\DynamoDbCache\DynamoDbCacheBuilder;

// you don't need to add the default one as well, it will be added automatically if it's missing
$converter = new CacheItemConverterRegistry(new MyCacheItemConverter());
$dynamoClient = new DynamoDbClient([]);
$cache = DynamoDbCacheBuilder::create('myTable', $dynamoClient)
    ->withConverterRegistry($converter)
    ->build();

$myOldCache = new MyCacheImplementation();
$cacheItem = $myOldCache->getItem('test'); // this is now an instance of MyCacheItem

// your custom converter will get used to convert it to DynamoCacheItem
// if you didn't supply your own converter, the \Omnilog\DynamoDbCache\Converter\DefaultCacheItemConverter
// would be used and the information about expiration date would be lost
$cache->save($cacheItem);

编码器

默认情况下，值使用 php 序列化器进行序列化。如果您想与其他语言的 app（或不同 php app，它们没有相同的类）共享缓存，您可以使用 \Omnilog\DynamoDbCache\Encoder\JsonItemEncoder 或编写自己的编码器。

注意：JsonItemEncoder 在处理对象时可能会丢失信息，如果您需要存储对象信息，此编码器可能不适合您。如果您只存储标量数据或数组，则 JsonItemEncoder 足够。

使用 JsonItemEncoder 的示例

<?php
use Omnilog\DynamoDbCache\DynamoDbCache;
use Omnilog\DynamoDbCache\DynamoDbCacheBuilder;
use AsyncAws\DynamoDb\DynamoDbClient;
use Omnilog\DynamoDbCache\Encoder\JsonItemEncoder;

$encoder = new JsonItemEncoder(); // with default flags and depth
$encoder = new JsonItemEncoder(JSON_PRETTY_PRINT, JSON_THROW_ON_ERROR, 100); // with custom encode and decode flags and depth

$cache = DynamoDbCacheBuilder::create('myTable', new DynamoDbClient([]))
    ->withEncoder($encoder)
    ->build();

您的值现在将作为 json 编码保存到 DynamoDB 中。

编写自己的编码器非常简单，您只需实现 \Omnilog\DynamoDbCache\Encoder\CacheItemEncoderInterface 接口

<?php

use Omnilog\DynamoDbCache\Encoder\CacheItemEncoderInterface;

class MyEncoder implements CacheItemEncoderInterface
{
    /**
     * @param mixed $input
     * @return string
     */
    public function encode($input) : string
    {
        // TODO: Implement encode() method.
    }

    /**
     * @param string $input
     * @return mixed
     */
    public function decode(string $input)
    {
        // TODO: Implement decode() method.
    }
}