SSDB is a high performance NoSQL database, an alternative for Redis, the official website is http://ssdb.io. This documentation describes the PHP client API of SSDB.
Notice: The phrases "hashmap", "hash", "map" are equivelant in SSDB.
<?php
include_once('SSDB.php');
try{
$ssdb = new SimpleSSDB('127.0.0.1', 8888);
}catch(Exception $e){
die(__LINE__ . ' ' . $e->getMessage());
}
$ret = $ssdb->set('key', 'value');
if($ret === false){
// error!
}
echo $ssdb->get('key');
SimpleSSDB throws Exception if it can't connect to SSDB server. Most methods(with some exceptions) return false on error. So one should use Identical Equal(===) to test the return value.
All methods will throw SSDBException on network error.
WARN: make sure all arguments do not exceed 10MB total size.
Creates a SSDB client, and connect to SSDB server. Throws exception if it can't connect to the server.
host - SSDB server's host/ip address.port - SSDB server's port number.timeout_ms - optional, timeout for connect, send/receive data, in milliseconds. Default 2000 ms.The SimpleSSDB instance.
$ssdb = new SimpleSSDB('127.0.0.1', 8888);
Since: 1.7.0.0
Config the password for later use to authenticate the connection. The authentication is not invoked immediately, but later when you send the first request to the server. Warning: The password is sent in plain-text over the network!
password - false on error, otherwise returns null.
$ssdb->auth('very-strong-password');
Set the value of the key.
key - value - false on error, other values indicate OK.
$ssdb->set('key', 'value');
Set the value of the key, with a time to live.
key - value - ttl - number of seconds to live.false on error, other values indicate OK.
$ssdb->setx('key', 'value', 60);
Set the string value in argument as value of the key if and only if the key doesn't exist.
key - value - false on error, 1: value is set, 0: key already exists.
$ssdb->setnx('key', 'value');
Set the time left to live in seconds, only for keys of KV type.
key - ttl - number of seconds to live.false on error, if key exists and ttl is set, return 1, if key not exists, return 0.
$ssdb->expire('key', 60);
Returns the time left to live in seconds, only for keys of KV type.
key - false on error, or time to live of the key, in seconds, -1 if there is no associated expire to the key.
$ssdb->ttl('key');
Get the value related to the specified key
key - Returns null if key not found, false on error, otherwise, the value related to that key is returned.
$ssdb->get('key');
Sets a value and returns the previous entry at that key.
key - value - Returns null if key not found, false on error, therwise, the value related to that key is returned.
$ssdb->getset('key', 'value');
Delete specified key.
key - false on error, other values indicate OK. You can not determine whether the key exists or not.
$ssdb->del('key');
Since 1.7.0.1, *incr methods return error if value cannot be converted to integer.
Increment the number stored at key by num. The num argument could be a negative integer. The old number is first converted to an integer before increment, assuming it was stored as literal integer.
key - num - Must be a signed integer.false on error, other values the new value.
$ssdb->incr('key', 1);
Verify if the specified key exists.
key - If the key exists, return true, otherwise return false.
$ssdb->exists('key');
Return a single bit out of a string.
key - offset - bit offset.0 or 1.
$ssdb->getbit('key', 7);
Changes a single bit of a string. The string is auto expanded.
key - offset - bit offset, must in range of [0, 1073741824].val - 0 or 1.The value of the bit before it was set: 0 or 1. If val is not 0 or 1, returns false.
$ssdb->setbit('key', 7, 1);
Like Redis's bitcount.
key - start - Optional, if start is negative, count from start'th character from the end of string.end - Optional.The number of bits set to 1.
$ssdb->bitcount('key', 2, 10);
Count the number of set bits (population counting) in part of a string.
key - start - Optional, if start is negative, count from start'th character from the end of string.size - Optional, if size is negative, then that many characters will be omitted from the end of string.The number of bits set to 1.
$ssdb->countbit('key', 2, 10);
Return part of a string(like PHP's substr()).
key - start - Optional, the offset of first byte returned. If start is negative, the returned string will start at the start'th character from the end of string.size - Optional, number of bytes returned. If size is negative, then that many characters will be omitted from the end of string.The extracted part of the string.
$ssdb->substr('key', 2, 10);
Return the number of bytes of a string.
key - The number of bytes of the string, if key not exists, returns 0.
$ssdb->strlen('key');
List keys in range (key_start, key_end].
("", ""] means no range limit.
key_start - The lower bound(not included) of keys to be returned, empty string means -inf(no limit).key_end - The upper bound(inclusive) of keys to be returned, empty string means +inf(no limit).limit - Up to that many elements will be returned.false on error, otherwise an array containing the keys.
$ssdb->keys('a', 'z', 10);
List key-value pairs with keys in range (key_start, key_end].
("", ""] means no range limit.
key_start - The lower bound(not included) of keys to be returned, empty string means -inf(no limit).key_end - The upper bound(inclusive) of keys to be returned, empty string means +inf(no limit).limit - Up to that many pairs will be returned.false on error, otherwise an associative array containing the key-value pairs.
$ssdb->scan('a', 'z', 10);
Iterate over all key-value pairs
$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;
}
List key-value pairs with keys in range (key_start, key_end], in reverse order.
("", ""] means no range limit.
key_start - The upper bound(not included) of keys to be returned, empty string means +inf(no limit).key_end - The lower bound(inclusive) of keys to be returned, empty string means -inf(no limit).limit - Up to that many pairs will be returned.false on error, otherwise an associative array containing the key-value pairs.
$ssdb->rscan('a', 'z', 10);
Set multiple key-value pairs(kvs) in one method call.
kvs - A associative array containing the key-value pairs.false on error, other values indicate OK.
$ssdb->multi_set(array( 'a' => 1, 'b' => 2, ));
Get the values related to the specified multiple keys
keys - An array containing keysfalse on error, otherwise an associative array containing ONLY found keys and values.
$ssdb->multi_get(array('k1', 'k2'));
Delete specified multiple keys.
keys - An array containing keysfalse on error, other values indicate OK.
$ssdb->multi_del(array('k1', 'k2'));
Set the string value in argument as value of the key of a hashmap.
name - The name of the hashmapkey - The key of the key-value pair in the hashmapvalue - The value of the key-value pair in the hashmapfalse on error, other values indicate OK.
$ssdb->hset('h', 'key', 'value');
Get the value related to the specified key of a hashmap
name - The name of the hashmapkey - The key of the key-value pair in the hashmapReturns null if key not found, false on error, otherwise, the value related to this key is returned.
$ssdb->hget('h', 'key');
Delete specified key of a hashmap.
name - The name of the hashmapkey - The key of the key-value pair in the hashmapfalse on error, other values indicate OK. You can not determine whether the key exists or not.
$ssdb->hdel('h', 'key');
Since 1.7.0.1, *incr methods return error if value cannot be converted to integer.
Increment the number stored at key in a hashmap by num. The num argument could be a negative integer. The old number is first converted to an integer before increment, assuming it was stored as literal integer.
name - The name of the hashmapkey - num - Must be a signed integer.false on error, other values the new value.
$ssdb->hincr('h', 'key', 1);
Verify if the specified key exists in a hashmap.
name - The name of the hashmapkey - If the key exists, return true, otherwise return false.
$ssdb->hexists('h', 'key');
Return the number of pairs of a hashmap.
name - The name of the hashmapfalse on error, otherwise an integer, 0 if the hashmap does not exist.
$ssdb->hsize('h');
List hashmap names in range (name_start, name_end].
("", ""] means no range limit.
name_start - The lower bound(not included) of names to be returned, empty string means -inf(no limit).name_end - The upper bound(inclusive) of names to be returned, empty string means +inf(no limit).limit - Up to that many elements will be returned.false on error, otherwise an array containing the names.
$ssdb->hlist('a', 'z', 10);
List keys of a hashmap in range (key_start, key_end].
("", ""] means no range limit.
name - The name of the hashmapkey_start - The lower bound(not included) of keys to be returned, empty string means -inf(no limit).key_end - The upper bound(inclusive) of keys to be returned, empty string means +inf(no limit).limit - Up to that many elements will be returned.false on error, otherwise an array containing the keys.
$ssdb->hkeys('h', 'a', 'z', 10);
Returns the whole hash, as an array of strings indexed by strings.
name - The name of the hashmapfalse on error, otherwise an associative array containing the key-value pairs.
$ssdb->hgetall('h');
List key-value pairs of a hashmap with keys in range (key_start, key_end].
("", ""] means no range limit.
name - The name of the hashmapkey_start - The lower bound(not included) of keys to be returned, empty string means -inf(no limit).key_end - The upper bound(inclusive) of keys to be returned, empty string means +inf(no limit).limit - Up to that many pairs will be returned.false on error, otherwise an associative array containing the key-value pairs.
$ssdb->hscan('h', 'a', 'z', 10);
Iterate over a 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];
}
List key-value pairs of a hashmap with keys in range (key_start, key_end], in reverse order.
("", ""] means no range limit.
name - The name of the hashmapkey_start - The upper bound(not included) of keys to be returned, empty string means +inf(no limit).key_end - The lower bound(inclusive) of keys to be returned, empty string means -inf(no limit).limit - Up to that many pairs will be returned.false on error, otherwise an associative array containing the key-value pairs.
$ssdb->hrscan('h', 'a', 'z', 10);
Delete all keys in a hashmap.
name - The name of the hashmap.false on error, or the number of keys deleted.
$ssdb->hclear('h');
Set multiple key-value pairs(kvs) of a hashmap in one method call.
name - The name of the hashmap.kvs - A associative array containing the key-value pairs.false on error, other values indicate OK.
$ssdb->multi_hset('h', array(
'a' => 1,
'b' => 2,
));
Get the values related to the specified multiple keys of a hashmap.
name - The name of the hashmap.keys - An array containing keys.false on error, otherwise an associative array containing ONLY found keys and values.
$ssdb->multi_hget('h', array('k1', 'k2'));
Delete specified multiple keys in a hashmap.
name - The name of the hashmap.keys - An array containing keys.false on error, other values indicate OK.
$ssdb->multi_hdel('h', array('k1', 'k2'));
Set the score of the key of a zset.
name - The name of the zsetkey - The key of the key-score pair in the hashmapscore - The score of the key-score pair in the hashmapfalse on error, other values indicate OK.
$ssdb->zset('z', 'key', 100);
Get the score related to the specified key of a zset
name - The name of the zsetkey - The key of the key-score pair in the zsetReturns null if key not found, false on error, otherwise, the score related to this key is returned.
$ssdb->zget('z', 'key');
Delete specified key of a zset.
name - The name of the zsetkey - The key of the key-score pair in the zsetfalse on error, other values indicate OK. You can not determine whether the key exists or not.
$ssdb->zdel('hz, 'key');
Increment the number stored at key in a zset by num. The num argument could be a negative integer. The old number is first converted to an integer before increment, assuming it was stored as literal integer.
name - The name of the zsetkey - num - Must be a signed integer.false on error, other values the new value.
$ssdb->zincr('z', 'key', 1);
Verify if the specified key exists in a zset.
name - The name of the zsetkey - If the key exists, return true, otherwise return false.
$ssdb->zexists('z', 'key');
Return the number of pairs of a zset.
name - The name of the zsetfalse on error, otherwise an integer, 0 if the zset does not exist.
$ssdb->zsize('z');
List zset names in range (name_start, name_end].
("", ""] means no range limit.
name_start - The lower bound(not included) of names to be returned, empty string means -inf(no limit).name_end - The upper bound(inclusive) of names to be returned, empty string means +inf(no limit).limit - Up to that many elements will be returned.false on error, otherwise an array containing the names.
$ssdb->zlist('a', 'z', 10);
List keys in a zset. See method zscan().
name - The name of the zsetkey_start - See method zscan().score_start - See method zscan().score_end - See method zscan().limit - Up to that many elements will be returned.false on error, otherwise an array containing the keys.
$ssdb->zkeys('z', '', 1, 100, 10);
List key-score pairs in a zset, where key-score in range (key_start+score_start, score_end]. If key_start is empty, keys with a score greater than or equal to score_start will be returned. If key_start is not empty, keys with score larger than score_start, and keys larger than key_start also with score equal to score_start will be returned.
That is: return keys in (key.score == score_start && key > key_start || key.score > score_start), and key.score <= score_end. The score_start, score_end is of higher priority than key_start.
("", ""] means no range limit.
name - The name of the zsetkey_start - The key related to score_start, could be empty string.score_start - The minimum score related to keys(may not be included, depend on key_start), empty string means -inf(no limit).score_end - The maximum score(inclusive) related to keys, empty string means +inf(no limit).limit - Up to that many pairs will be returned.false on error, otherwise an associative array containing the key-score pairs.
$ssdb->zscan('z', '', 1, 100, 10);
Iterate over zset:
$key_start = '';
$score_start = '';
while(1){
$items = $ssdb->zscan($zname, $key_start, $score_start, '', 10);
if(!$items){
break;
}
foreach($items as $key=>$score){
// process($key, $score)...
// remember the currently largest key and its score
$key_start = $key;
$score_start = $score;
}
}
List key-score pairs of a zset, in reverse order. See method zkeys().
name - The name of the zsetkey_start - See method zkeys().score_start - See method zkeys().score_end - See method zkeys().limit - Up to that many pairs will be returned.false on error, otherwise an associative array containing the key-score pairs.
$ssdb->zrscan('z', '', 100, 1, 10);
Important! This method may be extremly SLOW! May not be used in an online service.
Returns the rank(index) of a given key in the specified sorted set, starting at 0 for the item with the smallest score. zrrank starts at 0 for the item with the largest score.
name - The name of the zset.key - false on error, otherwise the rank(index) of a specified key, start at 0. null if not found.
$ssdb->zrank('z', 'k1');
Important! This method is SLOW for large offset!
Returns a range of key-score pairs by index range [offset, offset + limit). Zrrange iterates in reverse order.
name - The name of the zset.offset - Positive integer, the returned pairs will start at this offset.limit - Positive integer, up to this number of pairs will be returned.false on error, otherwise an array containing key-score pairs.
$ssdb->zrange('z', 0, 10);
Delete all keys in a zset.
name - The name of the zset.false on error, or the number of keys deleted.
$ssdb->zclear('z');
Returns the number of elements of the sorted set stored at the specified key which have scores in the range [start,end].
name - The name of the zset.start - The minimum score related to keys(inclusive), empty string means -inf(no limit).end - The maximum score related to keys(inclusive), empty string means +inf(no limit).false on error, or the number of keys in specified range.
$ssdb->zcount('z', 0, 100);
Returns the sum of elements of the sorted set stored at the specified key which have scores in the range [start,end].
name - The name of the zset.start - The minimum score related to keys(inclusive), empty string means -inf(no limit).end - The maximum score related to keys(inclusive), empty string means +inf(no limit).false on error, or the sum of keys in specified range.
$ssdb->zsum('z', 0, 100);
Returns the average of elements of the sorted set stored at the specified key which have scores in the range [start,end].
name - The name of the zset.start - The minimum score related to keys(inclusive), empty string means -inf(no limit).end - The maximum score related to keys(inclusive), empty string means +inf(no limit).false on error, or the average of keys in specified range.
$ssdb->zavg('z', 0, 100);
Delete the elements of the zset which have rank in the range [start,end].
name - The name of the zset.start - inclusive, unsigned number.end - inclusive, unsigned number.false on error, or the number of deleted elements.
$ssdb->zremrangebyrank('z', 1, 2);
Delete the elements of the zset which have score in the range [start,end].
name - The name of the zset.start - (inclusive).end - (inclusive).false on error, or the number of deleted elements.
$ssdb->zremrangebyscore('z', 1, 2);
Delete and return `limit` element(s) from front of the zset.
name - The name of the zset.limit - The number of elements to be deleted and returned.false on error, otherwise an array containing key-score pairs.
$ssdb->zpop_front('z', 3);
Delete and return `limit` element(s) from back of the zset.
name - The name of the zset.limit - The number of elements to be deleted and returned.false on error, otherwise an array containing key-score pairs.
$ssdb->zpop_back('z', 3);
Set multiple key-score pairs(kvs) of a zset in one method call.
name - The name of the zset.kvs - A associative array containing the key-score pairs.false on error, other values indicate OK.
$ssdb->multi_zset('z', array(
'a' => 1,
'b' => 2,
));
Get the values related to the specified multiple keys of a zset.
name - The name of the zset.keys - An array containing keys.false on error, otherwise an associative array containing ONLY found keys and values.
$ssdb->multi_zget('z', array('k1', 'k2'));
Delete specified multiple keys of a zset.
name - The name of the zset.keys - An array containing keys.false on error, other values indicate OK.
$ssdb->multi_zdel('z', array('k1', 'k2'));
Returns the number of items in the queue.
name - false on error, otherwise an integer, 0 if the queue does not exist.
$ssdb->qsize('q');
List list/queue names in range (name_start, name_end].
("", ""] means no range limit.
name_start - The lower bound(not included) of names to be returned, empty string means -inf(no limit).name_end - The upper bound(inclusive) of names to be returned, empty string means +inf(no limit).limit - Up to that many elements will be returned.false on error, otherwise an array containing the names.
$ssdb->qlist('a', 'z', 10);
Clear the queue.
name - false on error.
$ssdb->qclear('q');
Returns the first element of a queue.
name - false on error, null if queue empty, otherwise the item returned.
$ssdb->qfront('q');
Returns the last element of a queue.
name - false on error, null if queue empty, otherwise the item returned.
$ssdb->qback('q');
Returns the element a the specified index(position). 0 the first element, 1 the second ... -1 the last element.
name - index - negative intexes accepted.false on error, null if no element corresponds to this index, otherwise the item returned.
$ssdb->qget('q', -2);
Since: 1.7.0.0
Sets the list element at index to value. An error is returned for out of range indexes.
name - index - negative intexes accepted.val - false on error, other values indicate OK.
$ssdb->qset('q', 0, 'new val');
Returns a portion of elements from the queue at the specified range [offset, offset + limit].
name - offset - limit - false on error, otherwise an array containing items.
$ssdb->qrange('q', 0, -1);
Returns a portion of elements from the queue at the specified range [begin, end]. begin and end could be negative.
name - begin - end - false on error, otherwise an array containing items.
$ssdb->qslice('q', 0, -1);
This function is an alias of: qpush_back().
Adds one or more than one element to the head of the queue.
name - item - string or array of string.The length of the list after the push operation, false on error.
$ssdb->qpush_front('q', 'a');
Adds an or more than one element to the end of the queue.
name - item - string or array of string.The length of the list after the push operation, false on error.
$ssdb->qpush_back('q', 'a');
This function is an alias of: qpop_front().
Pop out one or more elements from the head of a queue.
name - size - optional, number of elements to pop, default is 1false on error. When size is not specified or less than 2, returns null if queue empty, otherwise the item removed. When size is specified and greater than or equal to 2, returns an array of elements removed.
$ssdb->qpop_front('q');
Pop out one or more elements from the tail of a queue.
name - size - optional, number of elements to pop, default is 1false on error. When size is not specified or less than 2, returns null if queue empty, otherwise the item removed. When size is specified and greater than or equal to 2, returns an array of elements removed.
$ssdb->qpop_back('q');
Remove multi elements from the head of a queue.
name - size - number of elements to delete.false on error. Return the number of elements removed.
$ssdb->qtrim_front('q', 3);
Remove multi elements from the tail of a queue.
name - size - number of elements to delete.false on error. Return the number of elements removed.
$ssdb->qtrim_back('q', 3);
Execute a batch of commands. Batch Commands can reduce the round trip time(rtt) between SSDB client and the server.
This feature is implemented in client side, the ssdb-server does not support batch command execution. The server will execute each command as if they are separated. The total amount of the commands and arguments must be less than 10MB.
exec() returns false on error, otherwise an array of results corresponding to each of the batch commands.
$ret = $ssdb->batch()
->set('a', 1)
->get('a')
->exec();
// or
$ssdb->batch();
$ssdb->set('a', 1);
$ssdb->get('a');
$ret = $ssdb->exec();
Return the approximate size of the database, in bytes. If compression is enabled, the size will be of the compressed data.
false on error. Return approximate size of the database, in bytes.
$ssdb->dbsize();
Return information about the server.
opt - optional, could be cmd, leveldbfalse on error. Return an associative array of information about the server.
$ssdb->info();