metatable

What is metatable?

metatable aims to provide simple interface to store and retrieve data. It is written entirely in PHP and uses only basic PHP functions, so no extensions are needed. But still metatable should be fast enough to be used as storage backend in some sort of applications. Data are stored in binary file in metatable's own format.

It is big hashmap, which associates (row : string, column : string) pair to value. Currently supported value types are: string, integer (32bit) and boolean. string is uninterpreted, so other types may be stored in their binary form as string. Maximal lengths of row and col are 124 bytes.

Basic usage

To open up metatable file use metatable::open():

require_once 'metatable.php';

$table = metatable::open('foo');

Either FALSE or newly created instance of metatable class is returned. metatable object has only a few public methods – get(), set(), index(), unindex() and close(). get() and set() are used to retrieve and store values. When passing NULL to set() as value, record is deleted:

$table->set('foo', 'bar', 5);

$table->get('foo', 'bar');
// => array('foo' => array('bar' => 5))

$table->set('foo', 'bar', NULL);

$table->get('foo', 'bar');
// => array()

index() and unindex() creates and drops indexes. Index is precomputed saved value, where data are stored in file. Indexes can be created only if there are some values to index.

The last method close() saves structure informations and closes metatable file. metatable is constructed in way that each instance is „transaction“ – all operations are performed or none of them – data integrity is assured.

Advanced usage

`metatable::open()` flags

metatable::open() takes two arguments – $filename and $flags, where $flags is integer – or-ed list of flags defined in metatable class constants. Possible flags are:

READONLY – metatable is opened readonly, cannot do set() and is not saved on closing (defautly turned off)
READWRITE – all operations are possible (defaulty on)
STRINGS_GC – strings are garbage collected (defaultly on)
AUTOCLOSE – automatically saved on instance destruction (defaultly off)

The most common option is to open metatable readonly, which increases efficiency, when you do not need to write to metatable:

$readonly = metatable::open('foo', metatable::READONLY);

Do not ever open more metatables, when one of them would be opened in READWRITE mode – this will cause race condition, each metatable will wait for the other one to aquire file lock.

Support

metatable should definitely work perfectly with PHP 5.2.0 or higher on any UNIX – this cover the most servers you can encounter. Lower versions of PHP 5 are probably without problems, too – please run tests and report if something does not work. With Windows is the problem that they does not give any support for atomic file handling. It is fixed with workaround, so metatable can be used without guaranted atomicity, but it is not as reliable as if running on any UNIX. metatable should be used on Windows only for development purposes.

License

metatable is licensed under the MIT License.