Table of Contents

Please enable javascript to display TOC.

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.