SSDB PHP程序api文档

@作者: ideawu

@更新: 2014-11-05

SSDB 是一个高性能 NoSQL 数据库, 支持 zset 数据结构, 用于替代 Redis. 官方网站是 http://ssdb.io. 本文档介绍了 SSDB 的 PHP 客户端 API.

注意: SSDB 所使用的名词 "hashmap", "hash", "map" 表示相同的意思.

类 SimpleSSDB

快速开始

<?php
include_once("SSDB.php");
try{
    $ssdb = new SimpleSSDB("127.0.0.1", 8888);
}catch(SSDBException $e){
    die(LINE . " " . $e->getMessage());
}
$ret = $ssdb->set("key", "value");
if($ret === false){
    // error!
}
echo $ssdb->get("key");

错误处理

如果无法连接到 SSDB 服务器, SimpleSSDB 将抛出异常. 大多数的方法(除了少数几个例外)通过返回 false 来标明出错. 所以要使用强制等于(===)来判断返回值.

如果出现网络错误, 所有的方法将会抛出 SSDBException 异常.

注意: 因为实现的原因, 请保证所有的参数加起来不超过 10MB 大小.

方法

SimpleSSDB::__construct

说明

创建 SimpleSSDB 的实例, 并连接到 SSDB 服务器. 如果无法连接到服务器, 将抛出异常.

参数

host - SSDB 服务器的主机名或者 IP.

port - SSDB 服务器的端口号.

timeout_ms - 可选, 连接超时时间, 和发送接收数据的超时时间, 单位毫秒. 默认是 2000 ms.

返回值

SimpleSSDB 的实例.

示例

$ssdb = new SimpleSSDB("127.0.0.1", 8888);

auth

Since: 1.7.0.0

说明

配置密码, 之后将用于向服务器校验. 这个校验不是立即进行的, 而是等你执行第一条命令的时候才发给服务器. 注意, 密码是明文传输的!

参数

password -

返回值

出错则返回 false, 否则返回 null.

示例

$ssdb->auth("very-strong-password");

set

说明

设置指定 key 的值内容.

参数

key -

value -

返回值

出错则返回 false, 其它值表示正常.

示例

$ssdb->set("key", "value");

setx

说明

设置指定 key 的值内容, 同时设置存活时间.

参数

key -

value -

ttl - 存活时间(秒)

返回值

出错则返回 false, 其它值表示正常.

示例

$ssdb->setx("key", "value", 60);

setnx

说明

当 key 不存在时, 设置指定 key 的值内容. 如果已存在, 则不设置.

参数

key -

value -

返回值

出错则返回 false, 1: value 已经设置, 0: key 已经存在, 不更新.

示例

$ssdb->setnx("key", "value");

expire

说明

设置 key(只针对 KV 类型) 的存活时间.

参数

key -

ttl - 存活时间(秒)

返回值

出错则返回 false. 如果 key 存在并设置成功, 返回 1, 如果 key 不存在, 返回 0.

示例

$ssdb->expire("key", 60);

ttl

说明

返回 key(只针对 KV 类型) 的存活时间.

参数

key -

返回值

出错则返回 false, 否则返回 key 的存活时间(秒), -1 表示没有设置存活时间.

示例

$ssdb->ttl("key");

get

说明

获取指定 key 的值内容.

参数

key -

返回值

如果 key 不存在则返回 null, 如果出错则返回 false, 否则返回 key 对应的值内容.

示例

$ssdb->get("key");

getset

说明

更新 key 对应的 value, 并返回更新前的旧的 value.

参数

key -

value -

返回值

如果 key 不存在则返回 null, 如果出错则返回 false, 否则返回 key 对应的值内容.

示例

$ssdb->getset("key", "value");

del

说明

删除指定的 key.

参数

key -

返回值

如果出错则返回 false, 其它值表示正常. 你无法通过返回值来判断被删除的 key 是否存在.

示例

$ssdb->del("key");

incr

从 1.7.0.1 起, 如果 value 不能转换成整数, incr 会返回错误.

说明

使 key 对应的值增加 num. 参数 num 可以为负数. 如果原来的值不是整数(字符串形式的整数), 它会被先转换成整数.

参数

key -

num - 可选, 必须是有符号整数, 默认是 1.

返回值

如果出错则返回 false, 否则返回新的值.

示例

$ssdb->incr("key", 1);

exists

说明

判断指定的 key 是否存在.

参数

key -

返回值

如果存在, 返回 true, 否则返回 false.

示例

$ssdb->exists("key");

getbit

说明

获取字符串内指定位置的位值(BIT).

参数

key -

offset - 位偏移

返回值

返回位值(0 或 1), 如果 key 不存在或者偏移超过活字符串长度范围, 返回 0.

示例

$ssdb->getbit("key", 9);

setbit

说明

设置字符串内指定位置的位值(BIT), 字符串的长度会自动扩展.

参数

key -

offset - 位偏移, 取值范围 [0, 1073741824]

val - 0 或 1

返回值

返回原来的位值. 如果 val 不是 0 或者 1, 返回 false.

示例

$ssdb->setbit("key", 9, 1);

bitcount

说明

计算字符串的子串所包含的位值为 1 的个数. 若 start 是负数, 则从字符串末尾算起. 若 end 是负数, 则表示从字符串末尾算起(包含). 类似 Redis 的 bitcount

参数

key -

start - 可选, 子串的字节偏移

end - 可选

返回值

返回位值为 1 的个数. 出错返回 false.

示例

$ssdb->bitcount("key", 2, 10);

countbit

说明

计算字符串的子串所包含的位值为 1 的个数. 若 start 是负数, 则从字符串末尾算起. 若 size 是负数, 则表示从字符串末尾算起, 忽略掉那么多字节.

参数

key -

start - 可选, 子串的字节偏移

size - 可选, 子串的长度(字节数), 默认为到字符串最后一个字节

返回值

返回位值为 1 的个数. 出错返回 false.

示例

$ssdb->countbit("key", 2, 10);

substr

说明

获取字符串的子串. 若 start 是负数, 则从字符串末尾算起. 若 size 是负数, 则表示从字符串末尾算起, 忽略掉那么多字节(类似 PHP 的 substr()).

参数

key -

start - 可选, int, 子串的字节偏移

size - 可选, int, 子串的长度(字节数), 默认为到字符串最后一个字节

返回值

字符串的子串.

示例

$ssdb->substr("key", 2, 10);

strlen

说明

计算字符串的长度(字节数).

参数

key -

返回值

返回字符串的长度, key 不存在则返回 0.

示例

$ssdb->strlen("key");

keys/rkeys

说明

列出处于区间 (key_start, key_end] 的 key 列表.

("", ""] 表示整个区间.

参数

key_start - 返回的起始 key(不包含), 空字符串表示 -inf.

key_end - 返回的结束 key(包含), 空字符串表示 +inf.

limit - 最多返回这么多个元素.

返回值

如果出错则返回 false, 否则返回包含 key 的数组.

示例

$ssdb->keys("a", "z", 10);

scan

说明

列出处于区间 (key_start, key_end] 的 key-value 列表.

("", ""] 表示整个区间.

参数

key_start - 返回的起始 key(不包含), 空字符串表示 -inf.

key_end - 返回的结束 key(包含), 空字符串表示 +inf.

limit - 最多返回这么多个元素.

返回值

如果出错则返回 false, 否则返回包含 key-value 的数关联组.

示例

$ssdb->scan("a", "z", 10);

$start = ""; 
$limit = 1000;
while(1){
    $kvs = $ssdb->scan($start, "", $limit);
    if(!$kvs){
        break;
    }
    // do something on key-value pairs...
    $keys = array_keys(array_slice($kvs, -1, 1, true));
    $max_key = $keys[0];
    $start = $max_key;
}

rscan

说明

列出处于区间 (key_start, key_end] 的 key-value 列表, 反向顺序.

("", ""] 表示整个区间.

参数

key_start - 返回的起始 key(不包含), 空字符串表示 +inf.

key_end - 返回的结束 key(包含), 空字符串表示 -inf.

limit - 最多返回这么多个元素.

返回值

如果出错则返回 false, 否则返回包含 key-value 的数关联组.

示例

$ssdb->rscan("a", "z", 10);

multi_set

说明

批量设置一批 key-value.

参数

kvs - 包含 key-value 的关联数组 .

返回值

出错则返回 false, 其它值表示正常.

示例

$ssdb->multi_set(array(
    "a" => 1,
    "b" => 2,
));

multi_get

说明

批量获取一批 key 对应的值内容.

参数

keys - 包含 key 的数组 .

返回值

如果出错则返回 false, 否则返回包含 key-value 的关联数组, 如果某个 key 不存在, 则它不会出现在返回数组中.

示例

$ssdb->multi_get(array("k1", "k2"));

multi_del

说明

批量删除一批 key 和其对应的值内容.

参数

keys - 包含 key 的数组 .

返回值

出错则返回 false, 其它值表示正常.

示例

$ssdb->multi_del(array("k1", "k2"));

hset

说明

设置 hashmap 中指定 key 对应的值内容.

参数

name - hashmap 的名字.

key - hashmap 中的 key.

value - key 对应的值内容.

返回值

出错则返回 false, 其它值表示正常.

示例

$ssdb->hset("h", "key", "value");

hget

说明

获取 hashmap 中指定 key 的值内容.

参数

name - hashmap 的名字.

key - hashmap 中的 key.

返回值

如果 key 不存在则返回 null, 如果出错则返回 false, 否则返回 key 对应的值内容.

示例

$ssdb->hget("h", "key");

hdel

说明

获取 hashmap 中的指定 key.

参数

name - hashmap 的名字.

key - hashmap 中的 key.

返回值

如果出错则返回 false, 其它值表示正常. 你无法通过返回值来判断被删除的 key 是否存在.

示例

$ssdb->hdel("h", "key");

hincr

从 1.7.0.1 起, 如果 value 不能转换成整数, incr 会返回错误.

说明

使 hashmap 中的 key 对应的值增加 num. 参数 num 可以为负数. 如果原来的值不是整数(字符串形式的整数), 它会被先转换成整数.

参数

name - hashmap 的名字.

key -

num - 可选, 必须是有符号整数, 默认是 1.

返回值

如果出错则返回 false, 否则返回新的值.

示例

$ssdb->hincr("h", "key", 1);

hexists

说明

判断指定的 key 是否存在于 hashmap 中.

参数

name - hashmap 的名字.

key -

返回值

如果存在, 返回 true, 否则返回 false.

示例

$ssdb->hexists("h", "key");

hsize

说明

返回 hashmap 中的元素个数.

参数

name - hashmap 的名字.

返回值

出错则返回 false, 否则返回元素的个数, 0 表示不存在 hashmap(空).

示例

$ssdb->hsize("h");

hlist, hrlist

说明

列出名字处于区间 (name_start, name_end] 的 hashmap.

("", ""] 表示整个区间.

参数

name_start - 返回的起始名字(不包含), 空字符串表示 -inf.

name_end - 返回的结束名字(包含), 空字符串表示 +inf.

limit - 最多返回这么多个元素.

返回值

出错则返回 false, 返回返回包含名字的数组.

示例

$ssdb->hlist("a", "z", 10);

hkeys

说明

列出 hashmap 中处于区间 (key_start, key_end] 的 key 列表.

("", ""] 表示整个区间.

参数

name - hashmap 的名字.

key_start - 起始 key(不包含), 空字符串表示 -inf.

key_end - 结束 key(包含), 空字符串表示 +inf.

limit - 最多返回这么多个元素.

返回值

如果出错则返回 false, 否则返回包含 key 的数组.

示例

$ssdb->hkeys("h", "a", "z", 10);

hgetall

说明

返回整个 hashmap.

参数

name - hashmap 的名字.

返回值

如果出错则返回 false, 否则返回包含 key-value 的关联数组.

示例

$ssdb->hgetall("h");

hscan

说明

列出 hashmap 中处于区间 (key_start, key_end] 的 key-value 列表.

("", ""] 表示整个区间.

参数

name - hashmap 的名字.

key_start - 返回的起始 key(不包含), 空字符串表示 -inf.

key_end - 返回的结束 key(包含), 空字符串表示 +inf.

limit - 最多返回这么多个元素.

返回值

如果出错则返回 false, 否则返回包含 key-value 的关联数组.

示例

$ssdb->hscan("h", "a", "z", 10);

遍历 hash:

$start = "";
while(1){
    $kvs = $ssdb->hscan($name, $start, "", 10);
    if(!$kvs){
        break;
    }
    // do sth on kvs here
$keys = array_keys($kvs);
$start = $keys[count($keys) - 1];
}

hrscan

说明

列出 hashmap 中处于区间 (key_start, key_end] 的 key-value 列表, 反向顺序.

("", ""] 表示整个区间.

参数

name - hashmap 的名字.

key_start - 返回的起始 key(不包含), 空字符串表示 +inf.

key_end - 返回的结束 key(包含), 空字符串表示 -inf.

limit - 最多返回这么多个元素.

返回值

如果出错则返回 false, 否则返回包含 key-score 的关联数组.

示例

$ssdb->hrscan("h", "a", "z", 10);

hclear

说明

删除 hashmap 中的所有 key.

参数

文章导航