SSDB PHP程序api文檔
SSDB PHP 客戶端 API 文檔
- @更新: 2014-11-05
SSDB 是一個(gè)高性能 NoSQL 數(shù)據(jù)庫, 支持 zset 數(shù)據(jù)結(jié)構(gòu), 用于替代 Redis. 官方網(wǎng)站是 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');錯(cuò)誤處理
如果無法連接到 SSDB 服務(wù)器, SimpleSSDB 將拋出異常. 大多數(shù)的方法(除了少數(shù)幾個(gè)例外)通過返回 false 來標(biāo)明出錯(cuò). 所以要使用強(qiáng)制等于(===)來判斷返回值.
如果出現(xiàn)網(wǎng)絡(luò)錯(cuò)誤, 所有的方法將會(huì)拋出 SSDBException 異常.
注意: 因?yàn)閷?shí)現(xiàn)的原因, 請(qǐng)保證所有的參數(shù)加起來不超過 10MB 大小.
方法
SimpleSSDB::__construct
說明
創(chuàng)建 SimpleSSDB 的實(shí)例, 并連接到 SSDB 服務(wù)器. 如果無法連接到服務(wù)器, 將拋出異常.
參數(shù)
host- SSDB 服務(wù)器的主機(jī)名或者 IP.port- SSDB 服務(wù)器的端口號(hào).timeout_ms- 可選, 連接超時(shí)時(shí)間, 和發(fā)送接收數(shù)據(jù)的超時(shí)時(shí)間, 單位毫秒. 默認(rèn)是 2000 ms.
返回值
SimpleSSDB 的實(shí)例.
示例
$ssdb = new SimpleSSDB('127.0.0.1', 8888);auth
Since: 1.7.0.0
說明
配置密碼, 之后將用于向服務(wù)器校驗(yàn). 這個(gè)校驗(yàn)不是立即進(jìn)行的, 而是等你執(zhí)行第一條命令的時(shí)候才發(fā)給服務(wù)器. 注意, 密碼是明文傳輸?shù)?
參數(shù)
password-
返回值
出錯(cuò)則返回 false, 否則返回 null.
示例
$ssdb->auth('very-strong-password');set
說明
設(shè)置指定 key 的值內(nèi)容.
參數(shù)
key-value-
返回值
出錯(cuò)則返回 false, 其它值表示正常.
示例
$ssdb->set('key', 'value');setx
說明
設(shè)置指定 key 的值內(nèi)容, 同時(shí)設(shè)置存活時(shí)間.
參數(shù)
key-value-ttl- 存活時(shí)間(秒)
返回值
出錯(cuò)則返回 false, 其它值表示正常.
示例
$ssdb->setx('key', 'value', 60);setnx
說明
當(dāng) key 不存在時(shí), 設(shè)置指定 key 的值內(nèi)容. 如果已存在, 則不設(shè)置.
參數(shù)
key-value-
返回值
出錯(cuò)則返回 false, 1: value 已經(jīng)設(shè)置, 0: key 已經(jīng)存在, 不更新.
示例
$ssdb->setnx('key', 'value');expire
說明
設(shè)置 key(只針對(duì) KV 類型) 的存活時(shí)間.
參數(shù)
key-ttl- 存活時(shí)間(秒)
返回值
出錯(cuò)則返回 false. 如果 key 存在并設(shè)置成功, 返回 1, 如果 key 不存在, 返回 0.
示例
$ssdb->expire('key', 60);ttl
說明
返回 key(只針對(duì) KV 類型) 的存活時(shí)間.
參數(shù)
key-
返回值
出錯(cuò)則返回 false, 否則返回 key 的存活時(shí)間(秒), -1 表示沒有設(shè)置存活時(shí)間.
示例
$ssdb->ttl('key');get
說明
獲取指定 key 的值內(nèi)容.
參數(shù)
key-
返回值
如果 key 不存在則返回 null, 如果出錯(cuò)則返回 false, 否則返回 key 對(duì)應(yīng)的值內(nèi)容.
示例
$ssdb->get('key');getset
說明
更新 key 對(duì)應(yīng)的 value, 并返回更新前的舊的 value.
參數(shù)
key-value-
返回值
如果 key 不存在則返回 null, 如果出錯(cuò)則返回 false, 否則返回 key 對(duì)應(yīng)的值內(nèi)容.
示例
$ssdb->getset('key', 'value');del
說明
刪除指定的 key.
參數(shù)
key-
返回值
如果出錯(cuò)則返回 false, 其它值表示正常. 你無法通過返回值來判斷被刪除的 key 是否存在.
示例
$ssdb->del('key');incr
從 1.7.0.1 起, 如果 value 不能轉(zhuǎn)換成整數(shù), incr 會(huì)返回錯(cuò)誤.
說明
使 key 對(duì)應(yīng)的值增加 num. 參數(shù) num 可以為負(fù)數(shù). 如果原來的值不是整數(shù)(字符串形式的整數(shù)), 它會(huì)被先轉(zhuǎn)換成整數(shù).
參數(shù)
key-num- 可選, 必須是有符號(hào)整數(shù), 默認(rèn)是 1.
返回值
如果出錯(cuò)則返回 false, 否則返回新的值.
示例
$ssdb->incr('key', 1);exists
說明
判斷指定的 key 是否存在.
參數(shù)
key-
返回值
如果存在, 返回 true, 否則返回 false.
示例
$ssdb->exists('key');getbit
說明
獲取字符串內(nèi)指定位置的位值(BIT).
參數(shù)
key-offset- 位偏移
返回值
返回位值(0 或 1), 如果 key 不存在或者偏移超過活字符串長度范圍, 返回 0.
示例
$ssdb->getbit('key', 9);setbit
說明
設(shè)置字符串內(nèi)指定位置的位值(BIT), 字符串的長度會(huì)自動(dòng)擴(kuò)展.
參數(shù)
key-offset- 位偏移, 取值范圍 [0, 1073741824]val- 0 或 1
返回值
返回原來的位值. 如果 val 不是 0 或者 1, 返回 false.
示例
$ssdb->setbit('key', 9, 1);bitcount
說明
計(jì)算字符串的子串所包含的位值為 1 的個(gè)數(shù). 若 start 是負(fù)數(shù), 則從字符串末尾算起. 若 end 是負(fù)數(shù), 則表示從字符串末尾算起(包含). 類似 Redis 的 bitcount
參數(shù)
key-start- 可選, 子串的字節(jié)偏移end- 可選
返回值
返回位值為 1 的個(gè)數(shù). 出錯(cuò)返回 false.
示例
$ssdb->bitcount('key', 2, 10);countbit
說明
計(jì)算字符串的子串所包含的位值為 1 的個(gè)數(shù). 若 start 是負(fù)數(shù), 則從字符串末尾算起. 若 size 是負(fù)數(shù), 則表示從字符串末尾算起, 忽略掉那么多字節(jié).
參數(shù)
key-start- 可選, 子串的字節(jié)偏移size- 可選, 子串的長度(字節(jié)數(shù)), 默認(rèn)為到字符串最后一個(gè)字節(jié)
返回值
返回位值為 1 的個(gè)數(shù). 出錯(cuò)返回 false.
示例
$ssdb->countbit('key', 2, 10);substr
說明
獲取字符串的子串. 若 start 是負(fù)數(shù), 則從字符串末尾算起. 若 size 是負(fù)數(shù), 則表示從字符串末尾算起, 忽略掉那么多字節(jié)(類似 PHP 的 substr()).
參數(shù)
key-start- 可選, int, 子串的字節(jié)偏移size- 可選, int, 子串的長度(字節(jié)數(shù)), 默認(rèn)為到字符串最后一個(gè)字節(jié)
返回值
字符串的子串.
示例
$ssdb->substr('key', 2, 10);strlen
說明
計(jì)算字符串的長度(字節(jié)數(shù)).
參數(shù)
key-
返回值
返回字符串的長度, key 不存在則返回 0.
示例
$ssdb->strlen('key');keys/rkeys
說明
列出處于區(qū)間 (key_start, key_end] 的 key 列表.
("", ""] 表示整個(gè)區(qū)間.
參數(shù)
key_start- 返回的起始 key(不包含), 空字符串表示 -inf.key_end- 返回的結(jié)束 key(包含), 空字符串表示 +inf.limit- 最多返回這么多個(gè)元素.
返回值
如果出錯(cuò)則返回 false, 否則返回包含 key 的數(shù)組.
示例
$ssdb->keys('a', 'z', 10);scan
說明
列出處于區(qū)間 (key_start, key_end] 的 key-value 列表.
("", ""] 表示整個(gè)區(qū)間.
參數(shù)
key_start- 返回的起始 key(不包含), 空字符串表示 -inf.key_end- 返回的結(jié)束 key(包含), 空字符串表示 +inf.limit- 最多返回這么多個(gè)元素.
返回值
如果出錯(cuò)則返回 false, 否則返回包含 key-value 的數(shù)關(guān)聯(lián)組.
示例
$ssdb->scan('a', 'z', 10);遍歷 key-value 對(duì)列表$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
說明
列出處于區(qū)間 (key_start, key_end] 的 key-value 列表, 反向順序.
("", ""] 表示整個(gè)區(qū)間.
參數(shù)
key_start- 返回的起始 key(不包含), 空字符串表示 +inf.key_end- 返回的結(jié)束 key(包含), 空字符串表示 -inf.limit- 最多返回這么多個(gè)元素.
返回值
如果出錯(cuò)則返回 false, 否則返回包含 key-value 的數(shù)關(guān)聯(lián)組.
示例
$ssdb->rscan('a', 'z', 10);multi_set
說明
批量設(shè)置一批 key-value.
參數(shù)
kvs- 包含 key-value 的關(guān)聯(lián)數(shù)組 .
返回值
出錯(cuò)則返回 false, 其它值表示正常.
示例
$ssdb->multi_set(array( 'a' => 1, 'b' => 2, ));
multi_get
說明
批量獲取一批 key 對(duì)應(yīng)的值內(nèi)容.
參數(shù)
keys- 包含 key 的數(shù)組 .
返回值
如果出錯(cuò)則返回 false, 否則返回包含 key-value 的關(guān)聯(lián)數(shù)組, 如果某個(gè) key 不存在, 則它不會(huì)出現(xiàn)在返回?cái)?shù)組中.
示例
$ssdb->multi_get(array('k1', 'k2'));
-
教程導(dǎo)航