README.md · spallation/LinkCache

# LinkCache - 一个灵活高效的PHP缓存工具库

LinkCache 是一个PHP编写的灵活高效的缓存工具库，提供多种缓存驱动支持，包括Memcache、Memcached、Redis、SSDB、文件缓存、APC、YAC等。通过LinkCache可以使不同缓存驱动实现操作统一，同时又可发挥不同缓存驱动各自的优势。LinkCache支持缓存 `object` 和 `array`，同时为防止产生惊群现象做了优化。

# 环境要求

- PHP >= 5.4
- 使用 Memcache 缓存需要安装[Memcache扩展](http://pecl.php.net/package/memcache)
- 使用 Memcached 缓存需要安装[Memcached扩展](http://pecl.php.net/package/memcached)
- 使用 Redis 缓存需要安装[Redis扩展](http://pecl.php.net/package/redis)
- 使用 APC 缓存需要安装[APC扩展](http://pecl.php.net/package/APC)
- 使用 YAC 缓存需要安装[YAC扩展](http://pecl.php.net/package/yac)

# 安装

## composer 安装
LinkCache 可以通过 `composer` 安装，使用以下命令从 `composer` 下载安装 LinkCache

```bash
$ composer require dongnan/linkcache
```

## 手动下载安装
### 下载地址
- 在 `Git@OSC` 下载 http://git.oschina.net/dongnan/LinkCache/tags
- 在 `GitHub` 下载 https://github.com/dongnan/LinkCache/releases

### 安装方法
在你的入口文件中引入
```php
<?php 
	//引入 LinkCache 的自动加载文件
	include("path_to_linkcache/autoload.php");
```

# 如何使用

(提示:如果以下锚点定位的链接错误，导致页面找不到等问题，请访问 https://github.com/dongnan/LinkCache 查看文档)

- [config](#config) - 配置信息
- [instance](#instance) - 缓存实例化
- [getDriver](#getdriver) - 获取缓存驱动实例
- [set](#set) - 将参数中的 `value`设置为 `key` 的值
- [setnx](#setnx) - 当缓存中不存在 `key` 时，将参数中的 `value` 设置为 `key` 的值
- [setDE](#setde) - 将参数中的 `value`设置为 `key` 的值，`key` 将自动延迟过期
- [get](#get) - 获取 `key` 对应的值
- [getDE](#getde) - 获取 `key` 对应的值，与 `setDE` 配合使用
- [del](#del) - 删除 `key`
- [has](#has) - 判断 `key` 是否存在
- [hasDE](#hasde) - 判断延迟过期的 `key` 理论上是否存在
- [ttl](#ttl) - 获取 `key` 的生存时间(单位:s)
- [ttlDE](#ttlde) - 获取延迟过期的 `key` 理论上的生存时间(单位:s)
- [expire](#expire) - 设置一个 `key` 的生存时间(单位:s)
- [expireDE](#expirede) - 以延迟过期的方式设置一个 `key` 的生存时间(单位:s)
- [expireAt](#expireat) - 用UNIX时间戳设置一个 `key` 的过期时间
- [expireAtDE](#expireatde) - 以延迟过期的方式用UNIX时间戳设置一个 `key` 的过期时间
- [persist](#persist) - 删除一个 `key` 的生存时间，使其永不过期
- [lock](#lock) - 对 `key` 设置锁标记（此锁并不对 `key` 做修改限制,仅为 `key` 的锁标记）
- [isLock](#islock) - 判断 `key` 是否有锁标记
- [unLock](#unlock) - 移除 `key` 的锁标记
- [incr](#incr) - 设置 `key` 的值按整数递增
- [incrByFloat](#incrbyfloat) - 设置 `key` 的值按浮点数递增
- [decr](#decr) - 设置 `key` 的值按整数递减
- [mSet](#mset) - 批量设置多个 `key` 对应的值
- [mSetNX](#msetnx) - 当缓存中不存在 `key` 时，批量设置多个 `key` 对应的值
- [mGet](#mget) - 获取所有给定 `key` 的值
- [mHas](#mhas) - 批量判断 `key` 是否存在
- [mDel](#mdel) - 批量删除 `key`

## config

配置信息

```php
<?php 
	//设置缓存配置, 使用 array_merge 的方式合并到默认配置中
	\linkcache\Cache::setConfig($config);
	
	//获取配置信息
	$config = \linkcache\Cache::getConfig();
	//获取指定缓存驱动的配置信息
	$config = \linkcache\Cache::getConfig('redis');

//默认配置信息
	[
		//默认使用的缓存驱动
		'default' => 'files',
        //当前缓存驱动失效时，使用的备份驱动
        'fallback' => 'files',
        'memcache' => [
            'servers' => [
                ['host' => '127.0.0.1', 'port' => 11211, 'weight' => 1, 'persistent' => true, 'timeout' => 1, 'retry_interval' => 15, 'status' => true],
            ],
            'compress' => ['threshold' => 2000, 'min_saving' => 0.2],
        ],
        'memcached' => [
            'servers' => [
                ['host' => '127.0.0.1', 'port' => 11211, 'weight' => 1],
            ],
            //参考 Memcached::setOptions
            'options' => [],
        ],
        'redis' => [
            'host' => '127.0.0.1',
            'port' => 6379,
            'password' => '',
            'database' => '',
            'timeout' => ''
        ],
        'ssdb' => [
            'host' => '127.0.0.1',
            'port' => 8888,
            'password' => '',
            'timeoutms' => ''
        ],
	]
```

## instance

实例化缓存对象

```php
<?php
	//直接new一个
	$cache = new \linkcache\Cache();
	//通过getInstance获取
	$cache = \linkcache\Cache::getInstance();

//根据驱动类型实例化,支持的驱动:redis,memcache,memcached,ssdb,files,apc,yac
	$cache = new \linkcache\Cache('files');
	//或者
	$cache = \linkcache\Cache::getInstance('files');

//传入配置参数实例化
	$cache = new \linkcache\Cache('redis', ['host' => '127.0.0.1', 'port' => 6379]);
```

## getDriver

获取缓存驱动实例

所有缓存驱动都必须实现 `linkcache\interfaces\driver\Base` 接口的方法，获取到缓存驱动实例后，可直接使用缓存驱动的方法，包括缓存驱动中没有定义但缓存驱动扩展对象中已定义的方法。

## set

将参数中的 `value` 设置为 `key` 的值

#### 参数
- key - 字符串
- value	- 除了 `resource` 类型的所有的值
- time - (可选参数) `key` 的生存时间，单位是秒(s)

#### 返回值
Boolean 如果设置成功，返回 `true`; 如果设置失败，返回 `false`

#### 例子

```php
<?php
	//设置不过期的缓存
	$status = $cache->set($key, $value);
	//设置有过期时间的缓存
	$status = $cache->set($key, $value, $time);
```

## setnx

当缓存中不存在 `key` 时，将参数中的 `value` 设置为 `key` 的值

#### 参数
- key - 字符串
- value	- 除了 `resource` 类型的所有的值
- time - (可选参数) `key` 的生存时间，单位是秒(s)

#### 返回值
Boolean - 如果设置成功，返回 `true`; 如果设置失败，返回 `false`

#### 例子

```php
<?php
	//设置不过期的缓存
	$status = $cache->setnx($key, $value);
	//设置有过期时间的缓存
	$status = $cache->setnx($key, $value, $time);
```

## setDE

将参数中的 `value`设置为 `key` 的值，`key` 将自动延迟过期

#### 参数
- key - 字符串
- value	- 除了 `resource` 类型的所有的值
- time - `key` 的生存时间，单位是秒(s)
- delayTime - (可选参数) 延迟过期时间，如果未设置，则使用配置中的设置

#### 返回值
Boolean - 如果设置成功，返回 `true`; 如果设置失败，返回 `false`

#### 例子

```php
<?php
	//设置不过期的缓存
	$status = $cache->setDE($key, $value);
	//设置有过期时间的缓存
	$status = $cache->setDE($key, $value, $time);
	//设置有过期时间的缓存并指定延迟过期时间
	$status = $cache->setDE($key, $value, $time, $delayTime);
```

## get

获取 `key` 对应的值

#### 参数
- key - 字符串

#### 返回值
Mixed - `key` 对应的值; 如果获取失败或 `key` 不存在，返回 `false`

#### 例子

```php
<?php
	//获取key对应的值
	$value = $cache->get($key);
```

## getDE

获取 `key` 对应的值，与 `setDE` 配合使用

#### 参数
- key - 字符串
- isExpired - `key` 理论上是否已经过期，这是一个引用变量，不需要初始化

#### 返回值
Mixed - `key` 对应的值; 如果获取失败或 `key` 不存在，返回 `false`

#### 例子

```php
<?php
	//获取key对应的值
	$value = $cache->getDE($key, $isExpired);
	//如果已经过期，处理其他逻辑
	if ($isExpired) {
		//TODO
	}
```

## del

删除 `key`

#### 参数
- key - 字符串

#### 返回值
Boolean - 如果删除成功，返回 `true`; 如果删除失败，返回 `false`。**注意：** 当 `key` 不存在时，也会返回 `true`

#### 例子

```php
<?php
	//删除key
	$status = $cache->del($key);
```

## has

判断 `key` 是否存在

#### 参数
- key - 字符串

#### 返回值
Boolean - 如果 `key` 存在，返回 `true`；如果 `key` 不存在，返回 `false`

#### 例子

```php
<?php
	//判断key是否存在
	$status = $cache->has($key);
```

## hasDE

判断延迟过期的 `key` 理论上是否存在。设置自动延期的 `key`，过期时间实际会被修改，用方法 `has` 判断的话，可能 `key` 仍然存在，但是理论上已经过期了

#### 参数
- key - 字符串

#### 返回值
Boolean - 如果 `key` 存在，返回 `true`；如果 `key` 不存在，返回 `false`

#### 例子

```php
<?php
	//判断key是否存在
	$status = $cache->hasDE($key);
```

## ttl

获取 `key` 的生存时间(单位:s)

#### 参数
- key - 字符串

#### 返回值
Mixed - 生存剩余时间(单位:秒) `-1` 表示永不过期,`-2` 表示 `key` 不存在,失败返回 `false`

#### 例子

```php
<?php
	//获取key的生存时间
	$ttl = $cache->ttl($key);
```

## ttlDE

获取延迟过期的 `key` 理论上的生存时间(单位:s)。

#### 参数
- key - 字符串

#### 返回值
Mixed - 生存剩余时间(单位:秒) `-1` 表示永不过期,`-2` 表示 `key` 不存在,失败返回 `false`

#### 例子

```php
<?php
	//获取延迟过期的 key 理论上的生存时间(单位:s)
	$ttl = $cache->ttlDE($key);
```

## expire

设置一个 `key` 的生存时间(单位:s)

#### 参数
- key - 字符串
- time - 整数，`key` 的生存时间(单位:s)