asfop/cache-kv

简化缓存操作的 PHP 库，专注于实现若无则从数据源获取并回填缓存这一常见模式

v1.1.0 2025-08-12 07:46 UTC

Requires

• php: >=7.0
• ext-redis: *

Requires (Dev)

• phpunit/phpunit: ^6.0|^7.0|^8.0|^9.0

MIT

• g1012415019

• redis
• performance
• php
• cache
• statistics
• key-value
• kv
• hot-key

README

CacheKV 是一个专注于简化缓存操作的 PHP 库，核心功能是实现"若无则从数据源获取并回填缓存"这一常见模式。

🎯 核心价值

CacheKV 让缓存操作变得简单：

// 一行代码搞定：检查缓存 → 未命中则获取数据 → 自动回填缓存
$data = kv_get('user.profile', ['id' => 123], function() {
    return getUserFromDatabase(123); // 只在缓存未命中时执行
});

解决的痛点：

• ❌ 手动检查缓存是否存在
• ❌ 缓存未命中时手动从数据源获取
• ❌ 手动将获取的数据写入缓存
• ❌ 批量操作时的复杂逻辑处理

⚡ 快速开始

安装

composer require asfop/cache-kv

基础使用

<?php
require_once 'vendor/autoload.php';

use Asfop\CacheKV\Core\CacheKVFactory;

// 配置Redis连接
CacheKVFactory::configure(function() {
    $redis = new Redis();
    $redis->connect('127.0.0.1', 6379);
    return $redis;
});

// 单个数据获取
$user = kv_get('user.profile', ['id' => 123], function() {
    return ['id' => 123, 'name' => 'John', 'email' => '[e-mail]'];
});

// 批量数据获取
$users = kv_get_multi('user.profile', [
    ['id' => 1], ['id' => 2], ['id' => 3]
], function($missedKeys) {
    $data = [];
    foreach ($missedKeys as $cacheKey) {
        $keyString = (string)$cacheKey;
        $params = $cacheKey->getParams();
        $data[$keyString] = getUserFromDatabase($params['id']);
    }
    return $data; // 返回关联数组
});

// 批量获取键对象（不执行缓存操作）
$keys = kv_get_keys('user.profile', [
    ['id' => 1], ['id' => 2], ['id' => 3]
]);

// 检查键配置
foreach ($keys as $keyString => $keyObj) {
    echo "键: {$keyString}, 有缓存配置: " . ($keyObj->hasCacheConfig() ? '是' : '否') . "\n";
}

🚀 核心功能

• 自动回填缓存：缓存未命中时自动执行回调并缓存结果
• 批量操作优化：高效的批量获取，避免N+1查询问题
• 按前缀删除：支持按键前缀批量删除缓存，相当于按 tag 删除
• 热点键自动续期：自动检测并延长热点数据的缓存时间
• 统计监控：实时统计命中率、热点键等性能指标
• 统一键管理：标准化键生成，支持环境隔离和版本管理

📊 统计功能

// 获取统计信息
$stats = kv_stats();
// ['hits' => 1500, 'misses' => 300, 'hit_rate' => '83.33%', ...]

// 获取热点键
$hotKeys = kv_hot_keys(10);
// ['user:profile:123' => 45, 'user:profile:456' => 32, ...]

// 清空统计数据
kv_clear_stats();

✨ 简洁API设计

CacheKV 提供了简洁易用的函数API：

🔧 核心操作

kv_get($template, $params, $callback, $ttl)      // 获取缓存
kv_get_multi($template, $paramsList, $callback)  // 批量获取

🗝️ 键管理

kv_key($template, $params)           // 创建键字符串
kv_keys($template, $paramsList)      // 批量创建键
kv_get_keys($template, $paramsList)  // 获取键对象

🗑️ 删除操作

kv_delete($template, $params)         // 删除指定缓存
kv_delete_prefix($template, $params)  // 按前缀删除
kv_delete_full($prefix)               // 按完整前缀删除

📊 统计功能

kv_stats()              // 获取统计信息
kv_hot_keys($limit)     // 获取热点键
kv_clear_stats()        // 清空统计

⚙️ 配置管理

kv_config()     // 获取配置对象（可转换为数组）

📚 文档

• 完整文档 - 详细的配置、架构和使用说明 ⭐
• 快速开始 - 5分钟快速上手指南
• 配置参考 - 所有配置选项的详细说明
• 统计功能 - 性能监控和热点键管理
• API 参考 - 完整的API文档
• 更新日志 - 版本更新记录

🏆 适用场景

• Web 应用 - 用户数据、页面内容缓存
• API 服务 - 接口响应、计算结果缓存
• 电商平台 - 商品信息、价格、库存缓存
• 数据分析 - 统计数据、报表缓存

📋 系统要求

• PHP >= 7.0
• Redis 扩展

📄 许可证

MIT License - 详见 LICENSE 文件

开始您的高效缓存之旅！ 🚀

💡 提示： 查看 完整文档 了解详细的配置和高级用法