PHP Library for accessing Kyoto Tycoon via Binary Protocol
published: 30 Dec 2012, last updated: 22 Jan 2013
Kyoto Tycoon is a lightweight database server with impressive performance. It can be accessed via several protocols, including an efficient binary protocol which is used in this PHP library.
The current implementation of this library provides access to the following commands: set_bulk
, get_bulk
, remove_bulk
(plus some wrapper functions to easily use these commands if you only need to access a single item) and play_script
. The functions set_bulk
, get_bulk
and remove_bulk
have been used in a production environment for several months without problems.
Due to a limitation of PHP, it is not possible to access items that have an absolute expiration time greater than 0x7fffffff
on 32bit systems. This limitation does not apply on 64bit systems and you can use the full feature set on a 64bit machine.
Download the Library
If you use this library, a link back to this website would be appreciated but is not required.
Documentation
The library consists of a single class named KyotoTycoon
. Exceptions thrown by its member functions are of type KyotoTycoon_Exception
.
The implementation of the class follows the singleton design pattern. You cannot directly create objects by calling the constructor. Instead, you have to call the member function get_connection
that returns a KyotoTycoon
object that is associated with a connection to the server. If you later call get_connection
with the same set of parameters again, the same connection will be returned and no resources are wasted. If you call get_connection
with a different set of parameters, a new connection will be openend, but the old connections remain alive. All connections are automatically closed when the program exits. A method to directly close connections is currently not implemented.
get_connection
static function get_connection(string $host=self::DEFAULT_HOST, int $port=self::DEFAULT_PORT, bool $lazy=TRUE, int $connect_timeout=NULL, int $timeout=NULL)
Parameters
- $host
The hostname or IP to connect to, defaults to
localhost
.- $port
The port number, defaults to
1978
which is the default port of Kyoto Tycoon.- $lazy
If set to
TRUE
, connection is not immediately established on object creation, instead it is openend automatically when required for the first time. This is the recommended setting, because opening a connection is only necessary if you actually use it.- $connect_timeout
Optional connection timeout, in seconds. Please read the fsockopen manual for further information.
- $timeout
Optional timeout for reading/writing data over the socket. Please read the stream_set_timeout manual for further information
Return Values
Always returns a KyotoTycoon
object. On failure, an exception is thrown.
get_metadata
Wrapper around stream_get_meta_data PHP function.
function get_metadata()
Return Values
Please read the stream_get_meta_data documentation for further information. If connection is not yet opened, it will throw an exception.
set_bulk
Stores multiple records at once.
function set_bulk(array $recs, int $flags=0)
Parameters
- $recs
Array of records. Each record is an associative array of 4 entries:
array('key'=>string, 'val'=>string, 'db'=>int, 'expire'=>int)
- $flags
If set to
KyotoTycoon::FLAG_NOREPLY
, function will not wait for an answer of the server.
Return Values
The number of actually stored records, or NULL
if $flags
was set to KyotoTycoon::FLAG_NOREPLY
.
set_bulk_kv
Wrapper function around set_bulk for simplifying the process of storing multiple records with equal expiration times in the same database.
function set_bulk_kv(array $kv, int $db, int $expire=NULL, int $flags=0)
Parameters
- $kv
Associative array of key/value pairs.
- $db
Database index to store the records in.
- $expire
Expiration time for all entries. The value that is used when setting $expire to
NULL
is0x7fffffff
on 32bit systems and0xffffffffff
on 64bit systems.- $flags
If set to
KyotoTycoon::FLAG_NOREPLY
, function will not wait for an answer of the server.
Return Values
The number of actually stored records, or NULL
if $flags
was set to KyotoTycoon::FLAG_NOREPLY
.
set
Wrapper function around set_bulk for easily storing a single item in the database.
function set(string $key, string $val, int $db, int $expire=NULL, int $flags=0)
Parameters
- $key
The key of the entry.
- $val
The value of the entry.
- $db
Database index to store the record in.
- $expire
Expiration time for entry. The value that is used when setting $expire to
NULL
is0x7fffffff
on 32bit systems and0xffffffffff
on 64bit systems.- $flags
If set to
KyotoTycoon::FLAG_NOREPLY
, function will not wait for an answer of the server.
Return Values
The number of actually stored records, or NULL
if $flags
was set to KyotoTycoon::FLAG_NOREPLY
.
get_bulk
Retrieves multiple records at once.
function get_bulk(array $recs, int $flags=0)
Parameters
- $recs
Array of record descriptions. Each record is an associative array of 2 entries:
array('key'=>string, 'db'=>int)
- $flags
Reserved and not used now.
Return Values
An array of records. Each record is an associative array of 4 entries: array('key'=>string, 'val'=>string, 'db'=>int, 'expire'=>int)
get_bulk_keys
Wrapper function around get_bulk for simplifying the process of retrieving multiple records from the same database.
get_bulk_keys(array $keys, int $db, int $flags=0)
Parameters
- $keys
Array of keys.
- $db
Database index.
- $flags
Reserved and not used now.
Return Values
Associative array of key/value pairs.
get
Wrapper function around get_bulk for easily retrieving a single item from the database.
function get(string $key, int $db, int $flags=0)
Parameters
- $key
The key of the entry.
- $db
Database index.
- $flags
Reserved and not used now.
Return Values
The value of the record, or NULL
if the record could not be found in the database.
remove_bulk
Remove multiple records at once.
function remove_bulk(array $recs, int $flags=0)
Parameters
- $recs
Array of record descriptions. Each record is an associative array of 2 entries:
array('key'=>string, 'db'=>int)
- $flags
If set to
KyotoTycoon::FLAG_NOREPLY
, function will not wait for an answer of the server.
Return Values
The number of removed records, or NULL
if $flags
was set to KyotoTycoon::FLAG_NOREPLY
remove_bulk_keys
Wrapper function around remove_bulk for simplifying the process of removing multiple records from the same database.
remove_bulk_keys(array $keys, int $db, int $flags=0)
Parameters
- $keys
Array of keys.
- $db
Database index.
- $flags
If set to
KyotoTycoon::FLAG_NOREPLY
, function will not wait for an answer of the server.
Return Values
The number of removed records, or NULL
if $flags
was set to KyotoTycoon::FLAG_NOREPLY
remove
Wrapper function around remove_bulk for easily removing a single item from the database.
function remove(string $key, int $db, int $flags=0)
Parameters
- $key
The key of the entry.
- $db
Database index.
- $flags
If set to
KyotoTycoon::FLAG_NOREPLY
, function will not wait for an answer of the server.
Return Values
The number of removed records, or NULL
if $flags
was set to KyotoTycoon::FLAG_NOREPLY
.
play_script
Calls a procedure of the LUA scripting language extension.
function play_script($name, $recs, $flags=0)
Parameters
- $name
The name of the LUA function.
- $recs
Array of records. Each record is an associative array of 2 entries:
array('key'=>string, 'val'=>string)
- $flags
If set to
KyotoTycoon::FLAG_NOREPLY
, function will not wait for an answer of the server.
Return Values
An array of records. Each record is an associative array of 2 entries: array('key'=>string, 'val'=>string)
. Or NULL
if $flags
was set to KyotoTycoon::FLAG_NOREPLY
.
Example
Here is a simple example.
<?php
require('KyotoTycoon.php');
$kt = KyotoTycoon::get_connection();
echo 'testkey = ';
var_dump($kt->get('testkey', 0));
echo 'setting testkey=testvalue... ';
var_dump($kt->set('testkey', 'testvalue', 0));
echo 'testkey = ';
var_dump($kt->get('testkey', 0));
echo 'removing testkey... ';
var_dump($kt->remove('testkey', 0));
echo 'testkey = ';
var_dump($kt->get('testkey', 0));
?>
The output should be:
testkey = NULL
setting testkey=testvalue... int(1)
testkey = string(9) "testvalue"
removing testkey... int(1)
testkey = NULL
Questions? Comments?
If you have questions regarding this library or suggestions for improvements, do not hesitate to contact me.