php_tokyocabinet-0.1.0

PHP PECL Tokyo Cabinet

php_tokyocabinet-0.1.0.tgz
Tokyo CabinetのPHPバインディングを作ってみました。
インストールは phpize; configure --enable-tokyocabinet; make; sudo make install と、いつもの手順ですが、configure内でpkg-configを使います。Tokyo Cabinetはバージョン1.0.2以降が必要です。
Mac OS XではTokyo Cabinet, pkg-configともにMacPortsでインストールできます。(databases/tokyocabinet, devel/pkgconfig)

API解説

ハッシュデータベースを操作するTCHDBクラス、B+木データベースを操作するTCBDBクラス、B+木データベースの各レコードを順番に参照するためのTCBDBCURクラスがあります。また、ユーティリティAPIのうち、エンコーディングに関連するものをTCUtilクラスののスタティックメソッドとして実装しました。
APIはTokyo CabinetのIDLにほぼ準拠していますが、Unicode文字列、透過的なシリアライズ、SPL (Iterator, ArrayAccess, Countable) の実装といった独自の拡張があります。独自拡張の使用例は配布物のexamplesディレクトリに含まれます。

TCHDB, TCBDB共通
void __construct([int $ktype[, int $vtype]])

PHPバインディングの独自拡張として、コンストラクタの第一引数でキーの扱いを、第二引数で値の扱いを、それぞれ設定することができる。(省略可)

キーの扱いを指定するクラス定数
定数名キーの扱い
TCHDB::KTBINARY
TCBDB::KTBINARY		 キーをバイナリ文字列として扱う。(デフォルト)
TCHDB::KTUNICODE
TCBDB::KTUNICODE		 キーをUnicode文字列として扱う。Unicode文字列の内部表現はUTF-16。(PHP6専用)
TCHDB::KTINT32
TCBDB::KTINT32		 キーを32ビットの符号付き整数として扱う。
TCHDB::KTINT64
TCBDB::KTINT64		 キーを64ビットの符号付き整数として扱う。
値の扱いを指定するクラス定数
定数名値の扱い
TCHDB::VTBINARY
TCBDB::VTBINARY		 値をバイナリ文字列として扱う。(デフォルト)
TCHDB::VTUNICODE
TCBDB::VTUNICODE		 値をUnicode文字列として扱う。Unicode文字列の内部表現はUTF-16。(PHP6専用)
TCHDB::VTSERIALIZED
TCBDB::VTSERIALIZED		 値を透過的にシリアライズ/アンシリアライズして挿入/取得する。

Tokyo Cabinetのデータベースフォーマットはバイトオーダーに依存しないが、独自拡張のUnicode文字列/32ビット整数キー/64ビット整数キーを選んだ場合、キーおよび値の読み書きの際のバイトオーダーはプラットフォームに依存する。バイナリ文字列およびシリアライズされたデータはバイトオーダーに依存しない。

int ecode(void)

最後に起こったエラーの番号を取得する。エラーモードがEMEXCEPTIONの場合は捕捉した例外のgetCodeメソッドでも取得できる。

string errmsg(int $ecode)

エラーコードに対応するメッセージを取得する。エラーモードがEMEXCEPTIONの場合は捕捉した例外のgetMessageメソッドでも取得できる。

bool seterrmode(int $emode)

PHPバインディング独自のメソッドで、エラー発生時の動作を設定する。

エラーモードを指定するクラス定数
定数名エラー発生時の動作
TCHDB::EMEXCEPTION
TCBDB::EMEXCEPTION		 例外TCExceptionをスローする。(デフォルト)
TCHDB::EMWARNING
TCBDB::EMWARNING		 E_WARNINGを発生してエラー時の戻り値を返す。
TCHDB::EMSILENT
TCBDB::EMSILENT		 何もせずエラー時の戻り値を返す。
bool setmutex(void)

複数のスレッドで安全にデータベースオブジェクトを共有するための排他制御を有効にする。PHPは言語としてスレッドプログラミングをサポートしておらず、ZTSモードでも他スレッドのオブジェクトは参照できないので使うことは無いと思われる。

bool open(string $path, int $omode)

データベースファイルを開いて接続する。接続モードは下記定数のビット和で指定する。

データベースに接続する方法を指定するクラス定数
定数名接続モード
TCHDB::OWRITER
TCBDB::OWRITER		 ライタ (読み書き両用) として接続する。接続中は他のプロセスはリーダとしてもライタとしても接続できない。
TCHDB::OREADER
TCBDB::OREADER		 リーダ (読み込み専用) として接続する。接続中は他のプロセスはリーダとしてもは接続できるが、ライタとしては接続できない。
TCHDB::OCREAT
TCBDB::OCREAT		 データベースが存在しない場合は作成する。OWRITERとのビット和で指定する。
TCHDB::OTRUNC
TCBDB::OTRUNC		 データベースを空にする。OWRITERとのビット和で指定する。
TCHDB::ONOLCK
TCBDB::ONOLCK		 データベースをロックせずに開く。OWRITER, OREADER両方にビット和で指定できる。
TCHDB::OLCKNB
TCBDB::OLCKNB		 データベースのロックを獲得できなかった場合は即座にエラーを発生してfalseを返す。OWRITER, OREADER両方にビット和で指定できる。
bool put(string $key, string $value)

レコードを挿入する。既に同じキーのレコードがある場合は上書きする。

bool putkeep(string $key, string $value)

レコードを挿入する。既に同じキーのレコードがある場合は何もしない。

bool putcat(string $key, string $value)

レコードに追記する。レコードがない場合は新規に作成する。

bool out(string $key)

レコードを削除する。

bool get(string $key)

レコードを取得する。

int vsiz(string $key)

レコードの大きさを取得する。B+木データベースでは最初に見つかったレコードの大きさを返す。レコードが存在しない場合は-1を返す。

bool sync(void)

データベースオブジェクトとデータベースファイルを同期する。

bool vanish(void)

全レコードを削除する。

string path(void)

データベースファイルのパス名を取得する。データベースに接続していない場合はnullを返す。

int rnum(void)

データベースの総レコード数を取得する。戻り値がPHP_INT_MAXを超える場合は数値を表す文字列を返す。データベースに接続していない場合は0を返す。

int fsiz(void)

データベースファイルの大きさを取得する。戻り値がPHP_INT_MAXを超える場合は数値を表す文字列を返す。データベースに接続していない場合は0を返す。

int count(void)

インターフェイスCountableで定義されているメソッド。count($db) としてもデータベースの総レコード数を取得できる。

bool offsetExists(string $key), string offsetGet(string $key), void offsetSet(string $key, string $value), void offsetUnset(string $key)

インターフェイスArrayAccessで定義されているメソッド。isset($db['foo']); echo $db['foo']; $db['foo'] = 'hop'; unset($db['foo']); といった連想配列風の操作が可能。

TCHDB
bool tune(int $bnum, int $apow, int $fpow, int $opt)

データベースを作成する前にチューニングパラメータを設定する。詳細はハッシュデータベースAPIの公式ドキュメントで。

bool putasync(string $key, string $value)

レコードを非同期に挿入する。既に同じキーのレコードがある場合は上書きする。渡されたレコードはバッファに蓄積された後、まとめてデータベースファイルに書き込まれる。

bool optimize(int $bnum, int $apow, int $fpow, int $opt)

データベースを作成した後に最適化する。各パラメータの意味はtuneメソッドに準ずる。

iterinit(), iternext()

TCHDBクラスはインターフェイスIteratorを実装しており、インスタンスをforeach文で使うことができるので、この2つのメソッドは実装していない。

TCBDB
bool setcmpfunc(callback $cmp[, mixed $cmpop])

キーを比較する関数を設定する。

キーを比較するコールバック関数を第一引数に、比較関数に渡されるオプションを第二引数に取る。オプションは省略してもよい。コールバック関数の代わりに下記クラス定数で組み込み比較関数を指定することもできる。組み込み比較関数ではオプションは無視される。

ユーザ定義比較関数の第一および第二引数はキーの文字列で、オプションが与えられていればそれが第三引数となる。比較関数は比較結果に応じて整数を返さなければならない。

組み込み比較関数を指定するクラス定数
定数名比較方法
TCBDB::CMPLEXICAL 辞書順で比較する。(デフォルト)
TCBDB::CMPDECIMAL 10進数を表す文字列として数値を比較する。
TCBDB::CMPINT32 32ビットの符号付き整数として比較する。
TCBDB::CMPINT64 64ビットの符号付き整数として比較する。
TCBDB::CMPUNICODE Unicode文字列としてBMP外の文字も一様に16ビットごとに辞書順で比較する。(PHP6専用)
TCBDB::CMPUNICODECP Unicode文字列としてコードポイントを比較する。BMP外の文字も正しく扱える。(PHP6専用)
bool tune(int $lmemb, int $nmemb, int $bnum, int $apow, int $fpow, int $opt)

データベースを作成する前にチューニングパラメータを設定する。詳細はB+木データベースAPIの公式ドキュメントで。

bool putdupall(string $key, array $values)

配列の各要素を同じキーに重複して挿入する。

bool outall(string $key)

指定されたキーに対応する全レコードを削除する。

array getall(string $key)

指定されたキーに対応する全レコードを取得する。

int vnum(string $key)

指定されたキーに対応するレコードの総数を取得する。

bool optimize(int $lmemb, int $nmemb, int $bnum, int $apow, int $fpow, int $opt)

データベースを作成した後に最適化する。各パラメータの意味はtuneメソッドに準ずる。

bool tranbegin(void)

トランザクションを開始する。

bool trancommit(void)

トランザクションをコミットする。

bool tranabort(void)

トランザクションをアボートする。

TCBDBITER getIterator(void)

インターフェイスIteratorAggregateのメソッドで、TCBDBITERを返す。TCBDBITERはPHPバインディング独自のクラスで、Iteratorを実装したTCBDBCURの兄弟。これによってTCBDBクラスのインスタンスをforeach文で使うことができる。

TCBDBCUR
void __construct(TCBDB $bdb)

コンストラクタ。

bool first(void)

カーソルを最初のレコードに移動する。レコードが存在しない場合はfalseを返す。

bool last(void)

カーソルを最後のレコードに移動する。レコードが存在しない場合はfalseを返す。

bool jump(string $key)

カーソルを指定されたキーまで移動する。レコードが存在しない場合はソート順で次のキーに移動し、falseを返す。

bool prev(void)

カーソルを前のレコードに移動する。レコードが存在しないか、カーソルが最初のレコードを指している場合はfalseを返す。

bool next(void)

カーソルを次のレコードに移動する。レコードが存在しないか、カーソルが最後のレコードを指している場合はfalseを返す。

bool put(string $value, int $cpmode)

レコードをカーソルの周辺に挿入する。

値の挿入位置を指定するクラス定数
定数名挿入位置
TCBDB::CPCURRENT 現在のレコードを上書きする。
TCBDB::CPBEFORE 現在のレコードの前に値を挿入する。
TCBDB::CPAFTER 現在のレコードの後に値を挿入する。
bool out(void)

現在のレコードを削除する。

string key(void)

現在のレコードのキーを取得する。

string val(void)

現在のレコードの値を取得する。

array rec(void)

現在のレコードのキーと値のペアを取得する。

TCBDBITER
void __construct(TCBDB $bdb[, bool $reverse])

コンストラクタ。TCBDBをforeach文で使った場合はTCBDB::getIterator()から暗黙的に呼ばれる。通常はレコードをキーの昇順で参照するが、$iter = new TCBDBITER($bdb, true); と、第二引数を真にしてインスタンスを作成した場合はレコードをキーの降順で参照する。

TCUtil
string urlencode(string $data), string urldecode(string $str)

データをURLエンコード/デコードする。

array urlbreak(string $str)

URLを構成要素ごとの連想配列に分割する。

string urlresolve(string $base, string $target)

絶対URL$baseに対する相対URL$targetを解決する。

string baseencode(string $data), string basedecode(string $str)

データをBase64エンコード/デコードする。

string quoteencode(string $data), string quotedecode(string $str)

データをQuoted-printableエンコード/デコードする。

string mimeencode(string $data, string $encname[, bool $base])

データをMIMEエンコードする。$encnameには文字セットのエンコーディング名を指定する。$baseにtrueが指定されるか省略された場合はBase64エンコーディング、$baseにfalseが指定された場合はQuoted-printableエンコーディングが使用される。

string mimedecode(string $str[, string &$encname])

MIMEエンコードされた文字列をデコードする。$encnameが与えられた場合はエンコーディング名が代入される。

string packencode(string $data), string packdecode(string $data)

データをPackbits圧縮/伸張する。

string bsencode(string $data), string bsdecode(string $data)

データをTCBS圧縮/伸張する。TCBSはTokyo Cabinet独自のブロックソートを用いたエンコーディング。

string deflate(string $data), string inflate(string $data)

データをDeflate圧縮/伸張する。

string gzipencode(string $data), string gzipdecode(string $data)

データをGZIP圧縮/伸張する。

string getcrc(string $data)

データのCRC32チェックサムを8桁の16進数として取得する。

string xmlescape(string $str), string xmlunescape(string $str)

XMLの特殊文字を実体参照にエスケープ/アンエスケープする。

array xmlbreak(string $str)

XML文字列を各タグとテキストノードの配列に分割する。

array xmlattrs(string $str)

XMLタグから属性名をキー、属性値を値をする連想配列を取得する

PHP6ではurlbreak, urlresolve, xmlescape, xmlunescape, xmlbreak, xmlattrsの各メソッドにUnicode文字列が引数として与えられた場合はUTF-8に変換して処理し、Unicode文字列に戻して返す。それ以外のメソッドはunicode.runtime_encodingに応じてバイナリ文字列に変換して処理し、バイナリ文字列を返す。いずれもunicode.semanticsには依らない。ただしgetcrcはunicode.semantics=OnならUnicode文字列を、Offならバイナリ文字列を返す。

グローバル定数
Tokyo Cabinetのバージョン文字列

TCVERSION

Tokyo Cabinet組み込みのエラー番号

TCESUCCESS, TCETHREAD, TCEINVALID, TCENOFILE, TCENOPERM, TCEMETA, TCERHEAD, TCEOPEN, TCECLOSE, TCETRUNC, TCESYNC, TCESTAT, TCESEEK, TCEREAD, TCEWRITE, TCEMMAP, TCELOCK, TCEUNLINK, TCERENAME, TCEMKDIR, TCERMDIR, TCEKEEP, TCENOREC, TCEMISC

PHPバインディング独自のエラー番号

TCMEINVALID, TCMEPARAM, TCMEUNSUPPORTED, TCMECONVERSION, TCMEUNIOCODE, TCMEMISC