This extension provides an API for communicating with Redis database, a persistent key-value database with built-in net interface written in ANSI-C for Posix systems.
It is a fork of alfonsojimenez's phpredis, adding many methods and fixing a lot of issues.
This code is maintained by Owlient. You can send comments, patches here on github or by email to:
phpize ./configure make && make install
You can generate a debian package for PHP5, accessible from Apache 2 by running ./mkdeb-apache2.sh.
This extension exports a single class, Redis.
Get the value related to the specified key
key
String or Bool: If key didn't exist, FALSE is returned. Otherwise, the value related to this key is returned.
$redis->get('key');
Set the string value in argument as value of the key.
Key Value
Bool TRUE if the command is successful.
$redis->set('key', 'value')
Set the string value in argument as value of the key if the target key already exists.
key value
Bool TRUE in case of success, FALSE in case of failure.
$this->redis->setnx('key', 'value'); /* return TRUE */
$this->redis->setnx('key', 'value'); /* return FALSE */
Remove specified keys.
key1 key2 key3 ... keyN
Long Number of keys deleted.
$redis->set('key1', 'val1');
$redis->set('key2', 'val2');
$redis->set('key3', 'val3');
$redis->delete('key1', 'key2', 'key3'); /* return 3 */
$redis->delete('key1', 'key2', 'key3'); /* return 0 */
Verify if the specified key exists.
key
BOOL: If the key exists, return TRUE, otherwise return FALSE.
$this->set('key', 'value');
$this->exists('key'); /* TRUE */
$this->exists('NonExistingKey'); /* FALSE */
Increment the number stored at key by one. If the second argument is filled, it will be used as the integer value of the increment.
key value: value that will be added to key
INT the new value
$redis->incr('key1'); /* key1 didn't exists, set to 0 before the increment */
/* and now has the value 1 */
$redis->incr('key1'); /* 2 */
$redis->incr('key1'); /* 3 */
$redis->incr('key1'); /* 4 */
Decrement the number stored at key by one. If the second argument is filled, it will be used as the integer value of the decrement.
key value: value that will be substracted to key
INT the new value
$redis->decr('key1'); /* key1 didn't exists, set to 0 before the increment */
/* and now has the value -1 */
$redis->decr('key1'); /* -2 */
$redis->decr('key1'); /* -3 */
Get the values of all the specified keys. If one or more keys dont exist, the array will contain FALSE at the position of the key.
Array: Array containing the list of the keys
Array: Array containing the values related to keys in argument
$redis->set('key1', 'value1');
$redis->set('key2', 'value2');
$redis->set('key3', 'value3');
$redis->getMultiple(array('key1', 'key2', 'key3')); /* array('value1', 'value2', 'value3');
$redis->getMultiple(array('key0', 'key1', 'key5')); /* array(`FALSE`, 'value2', `FALSE`);
Adds the string value to the head (left) of the list. Creates the list if the key didn't exist. If the key exists and is not a list, FALSE is returned.
key
value String, value to push in key
BOOL TRUE in case of success, FALSE in case of Failure.
$redis->lpush('key1', 'C');
$redis->lpush('key1', 'B');
$redis->lpush('key1', 'A'); /* key1 => [ 'A', 'B', 'C' ] */
Adds the string value to the tail (right) of the list. Creates the list if the key didn't exist. If the key exists and is not a list, FALSE is returned.
key
value String, value to push in key
BOOL TRUE in case of success, FALSE in case of Failure.
$redis->rpush('key1', 'A');
$redis->rpush('key1', 'B');
$redis->rpush('key1', 'C'); /* key1 => [ 'A', 'B', 'C' ] */
Returns and removes the last element of the list.
key
STRING if command executed successfully, BOOL FALSE in case of failure (key didn't exist)
$redis->rpush('key1', 'A');
$redis->rpush('key1', 'B');
$redis->rpush('key1', 'C'); /* key1 => [ 'A', 'B', 'C' ] */
$redis->rpop('key1'); /* key1 => [ 'A', 'B' ] */
Return and remove the first element of the list.
key
STRING in case of success (key exists)
STRING if command executed successfully, BOOL FALSE in case of failure (key didn't exist)
$redis->rpush('key1', 'A');
$redis->rpush('key1', 'B');
$redis->rpush('key1', 'C'); /* key1 => [ 'C', 'B', 'A' ] */
$redis->lpop('key1'); /* key1 => [ 'B', 'A' ] */
Returns and removes the first element of the list.
key
STRING in case of success (key exists)
BOOL FALSE in case of failure (key didn't exist)
$redis->rpush('key1', 'A');
$redis->rpush('key1', 'B');
$redis->rpush('key1', 'C'); /* key1 => [ 'C', 'B', 'A' ] */
$redis->rpop('key1'); /* key1 => [ 'C', 'B' ] */
Returns the size of a list identified by Key. If the list didn't exist or is empty, the command returns 0. If the data type identified by Key is not a list, the command return FALSE.
Key
LONG The size of the list identified by Key exists.
BOOL FALSE if the data type identified by Key is not list
$redis->rpush('key1', 'A');
$redis->rpush('key1', 'B');
$redis->rpush('key1', 'C'); /* key1 => [ 'C', 'B', 'A' ] */
$redis->lSize('key1');/* 3 */
$redis->rpop('key1');
$redis->lSize('key1');/* 2 */
Return the specified element of the list stored at the specified key.
0 the first element, 1 the second ...
-1 the last element, -2 the penultimate ...
Return FALSE in case of a bad index or a key that doesn't point to a list.
key index
String the element at this index
Bool FALSE if the key identifies a non-string data type, or no value corresponds to this index in the list Key.
$redis->rpush('key1', 'A');
$redis->rpush('key1', 'B');
$redis->rpush('key1', 'C'); /* key1 => [ 'A', 'B', 'C' ] */
$redis->lGet('key1', 0); /* 'A' */
$redis->lGet('key1', -1); /* 'C' */
$redis->lGet('key1', 10); /* `FALSE` */
Set the list at index with the new value.
key index value
BOOL TRUE if the new value is setted. FALSE if the index is out of range, or data type identified by key is not a list.
$redis->rpush('key1', 'A');
$redis->rpush('key1', 'B');
$redis->rpush('key1', 'C'); /* key1 => [ 'A', 'B', 'C' ] */
$redis->lGet('key1', 0); /* 'A' */
$redis->lSet('key1', 0, 'X');
$redis->lGet('key1', 0); /* 'X' */
Returns the specified elements of the list stored at the specified key in the range [start, end]. start and stop are interpretated as indices: 0 the first element, 1 the second ... -1 the last element, -2 the penultimate ...
key start end
Array containing the values in specified range.
$redis->rpush('key1', 'A');
$redis->rpush('key1', 'B');
$redis->rpush('key1', 'C');
$redis->lGetRange('key1', 0, -1); /* array('A', 'B', 'C') */
Trims an existing list so that it will contain only a specified range of elements.
key start stop
Array
Bool return FALSE if the key identify a non-list value.
$redis->rpush('key1', 'A');
$redis->rpush('key1', 'B');
$redis->rpush('key1', 'C');
$redis->lGetRange('key1', 0, -1); /* array('A', 'B', 'C') */
$redis->listTrim('key1', 0, 1);
$redis->lGetRange('key1', 0, -1); /* array('A', 'B') */
Removes the first count occurences of the value element from the list. If count is zero, all the matching elements are removed. If count is negative, elements are removed from tail to head.
key count value
LONG the number of elements to remove
BOOL FALSE if the value identified by key is not a list.
$redis->lpush('key1', 'A');
$redis->lpush('key1', 'B');
$redis->lpush('key1', 'C');
$redis->lpush('key1', 'A');
$redis->lpush('key1', 'A');
$redis->lGetRange('key1', 0, -1); /* array('A', 'A', 'C', 'B', 'A') */
$redis->lRemove('key1', 'A', 2); /* 2 */
$redis->lGetRange('key1', 0, -1); /* array('C', 'B', 'A') */
Adds a value to the set value stored at key. If this value is already in the set, FALSE is returned.
key value
BOOL TRUE if value didn't exist and was added successfully, FALSE if the value is already present.
$redis->sadd('key1' , 'set1'); /* TRUE, 'key1' => {'set1'} */
$redis->sadd('key1' , 'set2'); /* TRUE, 'key1' => {'set1', 'set2'}*/
$redis->sadd('key1' , 'set2'); /* FALSE, 'key1' => {'set1', 'set2'}*/
Removes the specified member from the set value stored at key.
key member
BOOL TRUE if the member was present in the set, FALSE if it didn't.
$redis->sadd('key1' , 'set1');
$redis->sadd('key1' , 'set2');
$redis->sadd('key1' , 'set3'); /* 'key1' => {'set1', 'set2', 'set3'}*/
$redis->sRemove('key1', 'set2'); /* 'key1' => {'set1', 'set3'} */
Moves the specified member from the set at srcKey to the set at dstKey.
srcKey dstKey member
BOOL If the operation is successful, return TRUE. If the srcKey and/or dstKey didn't exist, and/or the member didn't exist in srcKey, FALSE is returned.
$redis->sadd('key1' , 'set11');
$redis->sadd('key1' , 'set12');
$redis->sadd('key1' , 'set13'); /* 'key1' => {'set11', 'set12', 'set13'}*/
$redis->sadd('key2' , 'set21');
$redis->sadd('key2' , 'set22'); /* 'key2' => {'set21', 'set22'}*/
$redis->sMove('key1', 'key2', 'set13'); /* 'key1' => {'set11', 'set12'} */
/* 'key2' => {'set21', 'set22', 'set13'} */
Checks if value is a member of the set stored at the key key.
key value
BOOL TRUE if value is a member of the set at key key, FALSE otherwise.
$redis->sadd('key1' , 'set1');
$redis->sadd('key1' , 'set2');
$redis->sadd('key1' , 'set3'); /* 'key1' => {'set1', 'set2', 'set3'}*/
$redis->sContains('key1', 'set1'); /* TRUE */
$redis->sContains('key1', 'setX'); /* FALSE */
Returns the cardinality of the set identified by key.
key
LONG the cardinality of the set identified by key, 0 if the set doesn't exist.
$redis->sadd('key1' , 'set1');
$redis->sadd('key1' , 'set2');
$redis->sadd('key1' , 'set3'); /* 'key1' => {'set1', 'set2', 'set3'}*/
$redis->sSize('key1'); /* 3 */
$redis->sSize('keyX'); /* 0 */
Removes and returns a random element from the set value at Key.
key
String "popped" value
Bool FALSE if set identified by key is empty or doesn't exist.
$redis->sadd('key1' , 'set1');
$redis->sadd('key1' , 'set2');
$redis->sadd('key1' , 'set3'); /* 'key1' => {'set3', 'set1', 'set2'}*/
$redis->spop('key1'); /* 'set1', 'key1' => {'set3', 'set2'} */
$redis->spop('key1'); /* 'set3', 'key1' => {'set2'} */
Returns the members of a set resulting from the intersection of all the sets held at the specified keys.
If just a single key is specified, then this command produces the members of this set. If one of the keys
is missing, FALSE is returned.
key1, key2, keyN: keys identifying the different sets on which we will apply the intersection.
Array, contain the result of the intersection between those keys. If the intersection beteen the different sets is empty, the return value will be empty array.
$redis->sadd('key1', 'val1');
$redis->sadd('key1', 'val2');
$redis->sadd('key1', 'val3');
$redis->sadd('key1', 'val4');
$redis->sadd('key2', 'val3');
$redis->sadd('key2', 'val4');
$redis->sadd('key3', 'val3');
$redis->sadd('key3', 'val4');
var_dump($redis->sInter('key1', 'key2', 'key3'));
Output:
array(2) {
[0]=>
string(4) "val4"
[1]=>
string(4) "val3"
}
Performs a sInter command and stores the result in a new set.
Key: dstkey, the key to store the diff into.
Keys: key1, key2... keyN. key1..keyN are intersected as in sInter.
INTEGER: The cardinality of the resulting set, or FALSE in case of a missing key.
$redis = new Redis();
$redis->connect('127.0.0.1', 6379);
$redis->sadd('key1', 'val1');
$redis->sadd('key1', 'val2');
$redis->sadd('key1', 'val3');
$redis->sadd('key1', 'val4');
$redis->sadd('key2', 'val3');
$redis->sadd('key2', 'val4');
$redis->sadd('key3', 'val3');
$redis->sadd('key3', 'val4');
var_dump($redis->sInterStore('output', 'key1', 'key2', 'key3'));
var_dump($redis->sGetMembers('output'));
Output:
int(2)
array(2) {
[0]=>
string(4) "val4"
[1]=>
string(4) "val3"
}
Performs the union between N sets and returns it.
Keys: key1, key2, ... , keyN: Any number of keys corresponding to sets in redis.
Array of strings: The union of all these sets.
$redis->delete('s0', 's1', 's2');
$redis->sAdd('s0', '1');
$redis->sAdd('s0', '2');
$redis->sAdd('s1', '3');
$redis->sAdd('s1', '1');
$redis->sAdd('s2', '3');
$redis->sAdd('s2', '4');
var_dump($redis->sUnion('s0', 's1', 's2'));
Return value: all elements that are either in s0 or in s1 or in s2.
array(4) {
[0]=>
string(1) "3"
[1]=>
string(1) "4"
[2]=>
string(1) "1"
[3]=>
string(1) "2"
}
Performs the same action as sUnion, but stores the result in the first key
Key: dstkey, the key to store the diff into.
Keys: key1, key2, ... , keyN: Any number of keys corresponding to sets in redis.
INTEGER: The cardinality of the resulting set, or FALSE in case of a missing key.
$redis->delete('s0', 's1', 's2');
$redis->sAdd('s0', '1');
$redis->sAdd('s0', '2');
$redis->sAdd('s1', '3');
$redis->sAdd('s1', '1');
$redis->sAdd('s2', '3');
$redis->sAdd('s2', '4');
var_dump($redis->sUnionStore('dst', 's0', 's1', 's2'));
var_dump($redis->sMembers('dst'));
Return value: the number of elements that are either in s0 or in s1 or in s2.
int(4)
array(4) {
[0]=>
string(1) "3"
[1]=>
string(1) "4"
[2]=>
string(1) "1"
[3]=>
string(1) "2"
}
Performs the difference between N sets and returns it.
Keys: key1, key2, ... , keyN: Any number of keys corresponding to sets in redis.
Array of strings: The difference of the first set will all the others.
$redis->delete('s0', 's1', 's2');
$redis->sAdd('s0', '1');
$redis->sAdd('s0', '2');
$redis->sAdd('s0', '3');
$redis->sAdd('s0', '4');
$redis->sAdd('s1', '1');
$redis->sAdd('s2', '3');
var_dump($redis->sDiff('s0', 's1', 's2'));
Return value: all elements of s0 that are neither in s1 nor in s2.
array(2) {
[0]=>
string(1) "4"
[1]=>
string(1) "2"
}
Performs the same action as sDiff, but stores the result in the first key
Key: dstkey, the key to store the diff into.
Keys: key1, key2, ... , keyN: Any number of keys corresponding to sets in redis
INTEGER: The cardinality of the resulting set, or FALSE in case of a missing key.
$redis->delete('s0', 's1', 's2');
$redis->sAdd('s0', '1');
$redis->sAdd('s0', '2');
$redis->sAdd('s0', '3');
$redis->sAdd('s0', '4');
$redis->sAdd('s1', '1');
$redis->sAdd('s2', '3');
var_dump($redis->sDiffStore('dst', 's0', 's1', 's2'));
var_dump($redis->sMembers('dst'));
Return value: the number of elements of s0 that are neither in s1 nor in s2.
int(2)
array(2) {
[0]=>
string(1) "4"
[1]=>
string(1) "2"
}
Returns the contents of a set.
Key: key
An array of elements, the contents of the set.
$redis->delete('s');
$redis->sAdd('s', 'a');
$redis->sAdd('s', 'b');
$redis->sAdd('s', 'a');
$redis->sAdd('s', 'c');
var_dump($redis->sGetMembers('s'));
Output:
array(3) {
[0]=>
string(1) "c"
[1]=>
string(1) "a"
[2]=>
string(1) "b"
}
The order is random and corresponds to redis' own internal representation of the set structure.
Sets a value and returns the previous entry at that key.
Key: key
STRING: value
A string, the previous value located at this key.
$redis->set('x', '42');
$exValue = $redis->getSet('x', 'lol'); // return '42', replaces x by 'lol'
$newValue = $redis->get('x')' // return 'lol'
Returns a random key.
None.
STRING: an existing key in redis.
$key = $redis->randomKey(); $surprise = $redis->get($key); // who knows what's in there.
Switches to a given database.
INTEGER: dbindex, the database number to switch to.
TRUE in case of success, FALSE in case of failure.
(See following function)
Moves a key to a different database.
Key: key, the key to move.
INTEGER: dbindex, the database number to move the key to.
BOOL: TRUE in case of success, FALSE in case of failure.
$redis->select(0); // switch to DB 0
$redis->set('x', '42'); // write 42 to x
$redis->move('x', 1); // move to DB 1
$redis->select(1); // switch to DB 1
$redis->get('x'); // will return 42
Renames a key.
STRING: srckey, the key to rename.
STRING: dstkey, the new name for the key.
BOOL: TRUE in case of success, FALSE in case of failure.
$redis->set('x', '42');
$redis->renameKey('x', 'y');
$redis->get('y'); // → 42
$redis->get('x'); // → `FALSE`
Same as rename, but will not replace a key if the destination already exists. This is the same behaviour as setNx.
Sets an expiration date (a timeout) on an item.
Key: key. The key that will disappear.
Integer: ttl. The key's remaining Time To Live, in seconds.
BOOL: TRUE in case of success, FALSE in case of failure.
$redis->set('x', '42');
$redis->setTimeout('x', 3); // x will disappear in 3 seconds.
sleep(5); // wait 5 seconds
$this->get('x'); // will return `FALSE`, as 'x' has expired.
Returns the keys that match a certain pattern.
STRING: pattern, using '*' as a wildcard.
Array of STRING: The keys that match a certain pattern.
$allKeys = $redis->getKeys('*'); // all keys will match this.
$keyWithUserPrefix = $redis->getKeys('user*');
Returns the current database's size.
None.
INTEGER: DB size, in number of keys.
$count = $redis->dbSize(); echo "Redis has $count keys\n";
Authenticate the connection using a password. Warning: The password is sent in plain-text over the network.
STRING: password
BOOL: TRUE if the connection is authenticated, FALSE otherwise.
$redis->auth('foobared');
Performs a synchronous save.
None.
BOOL: TRUE in case of success, FALSE in case of failure. If a save is already running, this command will fail and return FALSE.
$redis->save();
Performs a background save.
None.
BOOL: TRUE in case of success, FALSE in case of failure. If a save is already running, this command will fail and return FALSE.
$redis->bgSave();
Returns the timestamp of the last disk save.
None.
INT: timestamp.
$redis->lastSave();
Returns the type of data pointed by a given key.
Key: key
Depending on the type of the data pointed by the key, this method will return the following value:
string: Redis::REDIS_STRING
set: Redis::REDIS_SET
list: Redis::REDIS_LIST
other: Redis::REDIS_NOT_FOUND
$redis->type('key');
Removes all entries from a given database.
INTEGER: dbindex, the database number to delete from. The first database has number zero.
BOOL: TRUE on success, FALSE on failure.
$redis->flushDB(0);
Removes all entries from all databases.
None.
BOOL: TRUE on success, FALSE on failure.
$redis->flushAll();
Returns an associative array of strings and integers, with the following keys:
- redis_version
- arch_bits
- uptime_in_seconds
- uptime_in_days
- connected_clients
- connected_slaves
- used_memory
- changes_since_last_save
- bgsave_in_progress
- last_save_time
- total_connections_received
- total_commands_processed
- role
None.
$redis->info();
Returns the time to live left for a given key, in seconds. If the key doesn't exist, FALSE is returned.
Key: key
Long, the time left to live in seconds.
$redis->ttl('key');
Sets multiple key-value pairs in one atomic command
Pairs: array(key => value, ...)
Bool TRUE in case of success, FALSE in case of failure.
$redis->mset(array('key0' => 'value0', 'key1' => 'value1'));
var_dump($redis->get('key0'));
var_dump($redis->get('key1'));
Output:
string(6) "value0" string(6) "value1"
Pops a value from the tail of a list, and pushes it to the front of another list. Also return this value.
Key: srckey
Key: dstkey
STRING The element that was moved in case of success, FALSE in case of failure.
$redis->delete('x', 'y');
$redis->lpush('x', 'abc');
$redis->lpush('x', 'def');
$redis->lpush('y', '123');
$redis->lpush('y', '456');
// move the last of x to the front of y.
var_dump($redis->rpoplpush('x', 'y'));
var_dump($redis->lGetRange('x', 0, -1));
var_dump($redis->lGetRange('y', 0, -1));
Output:
string(3) "abc"
array(1) {
[0]=>
string(3) "def"
}
array(3) {
[0]=>
string(3) "abc"
[1]=>
string(3) "456"
[2]=>
string(3) "123"
}