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.

PHP library to access Kyoto Tycoon (Version 0.2.0) (5.2 kB)

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 is 0x7fffffff on 32bit systems and 0xffffffffff 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 is 0x7fffffff on 32bit systems and 0xffffffffff 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.