kjdev/php-ext-msgpacki

PHP MessagePack Improved Extension

MessagePack 改良版拡張モジュール

msgpacki 拡張サポートによって MessagePack による変数のシリアライズ処理を行うこと ができるようになります。

MessagePack に関する詳細は » http://msgpack.org/ をご覧く ださい。

本家との主な差異

• 本家とは » Github にあるものを示します。
• 配列は Map として処理します。(動作モードにより異なります)
• convert に関しては未サポートです。
• シリアライズ/アンシリアライズ処理の前後にフィルタ処理を付与できます。
• 名前空間によるエイリアス関数を定義しています。(使用しないことも可能)

変更点

バージョン: 1.1.0

• msgpacki_unserialize()、msgpacki_decode()、MessagePacki::unpack() の引数に処理の成否を受け取る status を追加。

インストール

コンパイルオプション

通常は MessagePacki という名前空間でエイリアス関数が定義されますが、 「--disable-msgpacki-namespace」をビルドオプションに追加することで 名前空間のエイリアス関数を定義しないようにすることができます。

インストール

» Github にある最新のソースコー ドからコンパイルします。 Github に行き、"download" ボタンをクリックしましょう。 そして以下のようにします。

$ tar zxvf msgpacki-<commit_id>.tar.gz
$ cd msgpacki-<commit_id>
$ phpize
$ ./configure
$ sudo make install

コンパイルオプションを指定する場合は次のようにします。

./configure --disable-msgpacki-namespace

php.ini を次のように変更します。

• extension_dir 変数が msgpacki.so の場所を指すようにします。 ビルド中に、PHP ドライバをどこにインストールするのかがこのように表示されます。

  Installing '/usr/lib/php/extensions/no-debug-zts-20060613/msgpacki.so'
  

  この場所が PHP の拡張モジュール用ディレクトリと一致するかどうかは、 次のようにして確認します。

  $ php -i | grep extension_dir
    extension_dir => /usr/lib/php/extensions/no-debug-zts-20060613 =>
  /usr/lib/php/extensions/no-debug-zts-20060613
  

  もし一致しない場合は、php.ini の extension_dir を変更するか、 あるいは msgpacki.so を移動させます。

• PHP の起動時に拡張モジュールを読み込むために、次の行を追加します。

  extension=msgpacki.so
  

Fedora 17 および CentOS 6.2 のパッケージがあります。

• » Fedora 17
• » CentOS 6.2

Windows へのインストール

リリースごとのコンパイル済みバイナリがにあります。 アーカイブを Unzip して、php_msgpacki.dll を PHP 拡張モジュールのディレクトリ (デフォルトは "ext") に置きます。

• » PHP 5.4.8 VC9 Thread-Safe extension
• » PHP 5.4.8 VC9 Non-Thread-Safe extension

そして、php.ini に次の行を追加します。

extension=php_msgpacki.dll

php.ini オプション

php.ini の設定により動作が変化します。

msgpacki.mode int

• デフォルト: 2 (MSGPACKI_MODE_PHP)
• 変更可能: PHP_INI_ALL

シリアライズ処理の動作モードを設定します。

定義済み定数

以下の定数が定義されています。

• MSGPACKI_MODE_PHP

  標準の動作モードに指定します。 msgpacki_serialize()、msgpacki_unserialize() の動作は serialize()/unserialize() とほぼ同じように動作します。

  クラスや参照値のシリアル化は Map で処理して、1 つ目のキーに NULL を指定して バリュー値にクラス名や参照値を示すフラグを挿入しています。

• MSGPACKI_MODE_ORIGIN

  MSGPACKI_MODE_PHP と違いは次のものになります。

  • 参照値やシリアライズクラスの処理はサポートしません。
  • クラスオブジェクトはメンバ値を Map で処理します。
    • 内部処理的にオブジェクトの private および protected メンバのに付与されてい るクラス名や '*' は削除されます。
  • 配列は 0 からはじまる連続した数値でなければ Map で処理します。

  PHP 以外との言語でデータの受け渡しを行う時に使用してください。

• MSGPACKI_FILTER_REGISTER

  登録されているフィルタを指定します。

• MSGPACKI_FILTER_PRE_SERIALIZE

  msgpacki_serialize() の前に処理するフィルタを指定します。

• MSGPACKI_FILTER_POST_SERIALIZE

  msgpacki_serialize() の後に処理するフィルタを指定します。

• MSGPACKI_FILTER_PRE_UNSERIALIZE

  msgpacki_unserialize() の前に処理するフィルタを指定します。

• MSGPACKI_FILTER_POST_UNSERIALIZE

  msgpacki_unserialize() の後に処理するフィルタを指定します。

関数

一覧

• msgpacki_serialize — 値の保存可能な表現を生成する
• msgpacki_unserialize — 保存用表現から PHP の値を生成する
• msgpacki_encode — 値の保存可能な表現を生成する
• msgpacki_decode — 保存用表現から PHP の値を生成する
• msgpacki_filter_register — フィルタを登録する
• msgpacki_filter_append — フィルタをリストの末尾に付与する
• msgpacki_filter_prepend — フィルタをリストの先頭に付与する
• msgpacki_filter_remove — フィルタを取り除く
• msgpacki_get_filters — フィルタのリストを取得する

msgpacki_serialize — 値の保存可能な表現を生成する

説明

string msgpacki_serialize ( mixed $value )

値の保存可能な表現を生成します。

シリアル化された文字列を PHP の値に戻すには、msgpacki_unserialize() を使用し てください。

パラメータ

• value

  シリアル化する値。 msgpacki_serialize() は、resource 以外の全ての型を処理します。

  PHP は、シリアル化の前にまずメンバ関数 __sleep() のコールをします。ここで、シ リアル化の前のオブジェクトの後始末処理などを行います。

返り値

value の保存可能なバイトストリーム表現を含む文字列を返します。

msgpacki_unserialize — 保存用表現から PHP の値を生成する

説明

mixed msgpacki_unserialize ( string $str [, bool &$status ] )

シリアル化された変数を PHP 変数値に戻す変換を行います。

パラメータ

• str

  シリアル化された文字列。

  もしアンシリアライズする変数がオブジェクトの場合、オブジェクトが無事再作成され た後、PHP は自動的にメンバ関数 __wakeup() (存在していれば) をコールしようとし ます。

• status

  処理の成否結果。

  status が指定された場合、正常に処理できた場合は TRUE、 それ以外は FALSE が保存されます。

返り値

変換された値が返されます。

渡された文字列が復元できなかった場合、FALSE を返して E_NOTICE を発生します。

msgpacki_encode — 値の保存可能な表現を生成する

基本的に msgpacki_serialize() と同じですが、 この関数は動作モードが MSGPACKI_MODE_ORIGIN 固定となっています。

説明

string msgpacki_encode ( mixed $value [, int options = MSGPACKI_MODE_ORIGIN ] )

値の保存可能な表現を生成します。

パラメータ

• value

  シリアル化する値。

• options

  動作モード。

返り値

value の保存可能なバイトストリーム表現を含む文字列を返します。

msgpacki_decode — 保存用表現から PHP の値を生成する

基本的に msgpacki_unserialize() と同じですが、 この関数は動作モードが MSGPACKI_MODE_ORIGIN 固定となっています。

説明

mixed msgpacki_decode ( string $str [, int options = MSGPACKI_MODE_ORIGIN, bool &$status ] )

シリアル化された変数を PHP 変数値に戻す変換を行います。

パラメータ

• str

  シリアル化された文字列。

• options

  動作モード。

• status

  処理の成否結果。

  status が指定された場合、正常に処理できた場合は TRUE、 それ以外は FALSE が保存されます。

返り値

変換された値が返されます。

渡された文字列が復元できなかった場合、FALSE を返して E_NOTICE を発生します。

msgpacki_filter_register — フィルタを登録する

説明

bool msgpacki_filter_register ( string $filtername , string $classname )

シリアライズ/アンシリアライズの関数で使うことのできるカスタムフィルタを登録します。

パラメータ

• filtername

  登録するフィルタ名。

• classname

  カスタムフィルタのクラス名。

  フィルタを実装するには、MessagePacki_Filter を継承したクラスのメンバ関数を実 装しなくてはなりません。

  メソッドの実装は、MessagePacki_Filter の説明の通りにしなければなりません。 さもないと、定義されていない動作をします。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

msgpacki_filter_append — フィルタをリストの末尾に付与する

説明

bool msgpacki_filter_append ( string $filtername )

filtername で指定されたフィルタをフィルタのリストの末尾に加えます。

パラメータ

• filtername

  フィルタ名。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

msgpacki_filter_prepend — フィルタをリストの先頭に付与する

説明

bool msgpacki_filter_prepend ( string $filtername )

filtername で指定されたフィルタをフィルタのリストの先頭に加えます。

パラメータ

• filtername

  フィルタ名。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

msgpacki_filter_remove — フィルタを取り除く

説明

bool msgpacki_filter_remove ( string $filtername )

事前に msgpacki_filter_append() あるいは msgpacki_filter_prepend() で追 加したフィルタを削除します。

パラメータ

• filtername

  フィルタ名。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

msgpacki_get_filters — フィルタのリストを取得する

説明

array msgpacki_get_filters ( [ string $type ] )

登録されているフィルタの一覧を取得します。

パラメータ

• type

  フィルタタイプ。

  MSGPACKI_FILTER_REGISTER, MSGPACKI_FILTER_PRE_SERIALIZE, MSGPACKI_FILTER_POST_SERIALIZE, MSGPACKI_FILTER_PRE_UNSERIALIZE, MSGPACKI_FILTER_POST_UNSERIALIZE。

返り値

使用可能フィルタの名前を含む配列を返します。

type を指定しない場合は type を配列のキーにしたものを返します。

クラス

一覧

• MessagePacki — シリアライズ/アンシリアライズクラス
• MessagePacki_Filter — フィルタクラス

MessagePacki — シリアライズ/アンシリアライズクラス

クラス概要

MessagePacki {
    /* メソッド */
    public __construct( [ int $mode = MSGPACKI_MODE_PHP ] )
    public string pack( mixed $value )
    public mixed unpack( string $str [, bool &$status ] )
    public int get_mode()
    public bool set_mode( int $mode )
    public bool append_filter( string $name )
    public bool prepend_filter( string $name )
    public bool remove_filter( string $name )
    public array get_filters( string $type )

    /* エイリアス */
    alias int getMode()
    alias bool setMode( int $mode )
    alias appendFilter( string $name )
    alias prependFilter( string $name )
    alias removeFilter( string $name )
    alias getFilters( string $type )
}

メソッド一覧

• MessagePacki::__construct — 新しいシリアライズ/アンシリアライズオブジェクトを作成する
• MessagePacki::pack — 値の保存可能な表現を生成する
• MessagePacki::unpack — 保存用表現から PHP の値を生成する
• MessagePacki::get_mode — 動作モードを取得する
• MessagePacki::set_mode — 動作モードを設定する
• MessagePacki::append_filter — フィルタをリストの末尾に付与する
• MessagePacki::prepend_filter — フィルタをリストの先頭に付与する
• MessagePacki::remove_filter — フィルタを取り除く
• MessagePacki::get_filters — フィルタのリストを取得する

MessagePacki::__construct — 新しいシリアライズ/アンシリアライズオブジェクトを作成する

説明

public MessagePacki::__construct ( [ int $mode = MSGPACKI_MODE_PHP ] )

パラメータ

• mode

  MessagePack シリアライズ処理の動作モード。

  既定値は MSGPACKI_MODE_PHP。

返り値

新しいシリアライズ/アンシリアライズオブジェクトを返します。

MessagePacki::pack — 値の保存可能な表現を生成する

説明

public string MessagePacki::pack ( mixed $value )

値の保存可能な表現を生成します。

msgpacki_serialize() と同様の処理を行います。

パラメータ

• value

  シリアル化する値。

返り値

value の保存可能な文字列を返します。

MessagePacki::unpack — 保存用表現から PHP の値を生成する

説明

public mixed MessagePacki::unpack ( string $str [, bool &$status ] )

シリアル化された変数を PHP 変数値に戻す変換を行います。

msgpacki_unserialize() と同様の処理を行います。

パラメータ

• str

  シリアル化された文字列。

• status

  処理の成否結果。

  status が指定された場合、正常に処理できた場合は TRUE、 それ以外は FALSE が保存されます。

返り値

変換された値が返されます。

MessagePacki::get_mode — 動作モードを取得する

説明

public int MessagePacki::get_mode ()

動作モードを取得します。

返り値

動作モード値を返します。

MessagePacki::set_mode — 動作モードを設定する

説明

public bool MessagePacki::set_mode ( int $mode )

動作モードを設定します。

ここで設定した動作モードに処理 MessagePacki::pack() 、 MessagePacki::unpack() の 処理が変わります。

パラメータ

• mode

  動作モード値。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

MessagePacki::append_filter — フィルタをリストの末尾に付与する

説明

public bool MessagePacki::append_filter ( string $name )

name で指定されたフィルタをフィルタリストの末尾に加えます。

パラメータ

• name

  フィルタ名またはクラス名。

  msgpacki_filter_register() により登録されているフィルタと同名のものがある場合 はそのフィルタをフィルタリストに加えます。 同名のフィルタがない場合はその名前のクラスを登録します。

  フィルタクラスは MessagePacki_Filter を継承する必要があります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

MessagePacki::prepend_filter — フィルタをリストの先頭に付与する

説明

public bool MessagePacki::prepend_filter ( string $name )

name で指定されたフィルタをフィルタリストの先頭に加えます。

パラメータ

• name

  フィルタ名またはクラス名。

  msgpacki_filter_register() により登録されているフィルタと同名のものがある場合 はそのフィルタをフィルタリストに加えます。 同名のフィルタがない場合はその名前のクラスを登録します。

  フィルタクラスは MessagePacki_Filter を継承する必要があります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

MessagePacki::remove_filter — フィルタを取り除く

説明

public bool MessagePacki::remove_filter ( string $name )

MessagePacki::append_filter() あるいは MessagePacki::prepend_filter() で追加し たフィルタを削除します。

パラメータ

• name

  フィルタ名またはクラス名。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

MessagePacki::get_filters — フィルタのリストを取得する

説明

public array MessagePacki::get_filters ( [ string $type ] )

登録されているフィルタの一覧を取得します。

パラメータ

• type

  フィルタタイプ。

返り値

使用可能フィルタの名前を含む配列を返します。

type を指定しない場合は type を配列のキーにしたものを返します。

MessagePacki_Filter — フィルタクラス

このクラスの子クラスを msgpacki_filter_register() に渡します。

クラス概要

MessagePacki\_Filter {
    /* プロパティ */
    public $filterename;

    /* メソッド */
    public mixed pre_serialize ( mixed $in )
    public string post_serialize ( string $in )
    public string pre_unserialize ( string $in )
    public mixed post_unserialize ( mixed $in )
}

プロパティ

• filtername

  msgpacki_filter_register() で登録するフィルタの名前。

メソッド一覧

• MessagePacki_Filter::pre_serialize — シリアライズ処理前に実行される
• MessagePacki_Filter::post_serialize — シリアライズ処理後に実行される
• MessagePacki_Filter::pre_unserialize — アンシリアライズ処理前に実行される
• MessagePacki_Filter::post_unserialize — アンシリアライズ処理後に実行される

MessagePacki_Filter::pre_serialize — シリアライズ処理前にコールされる

説明

public mixed MessagePacki_Filter::pre_serialize ( mixed $in )

このメソッドがコールされるのは、シリアライズ処理が実行される前です。

パラメータ

• in

  シリアライズ化する値。

返り値

フィルタ処理したシリアライズ処理に渡す値。

MessagePacki_Filter::post_serialize — シリアライズ処理後にコールされる

説明

public string MessagePacki_Filter::pre_serialize ( string $in )

このメソッドがコールされるのは、シリアライズ処理が実行された後です。

パラメータ

• in

  シリアル化された文字列。

返り値

フィルタ処理したシリアル化された文字列。

MessagePacki_Filter::pre_unserialize — アンシリアライズ処理前にコールされる

説明

public string MessagePacki_Filter::pre_unserialize ( string $in )

このメソッドがコールされるのは、アンシリアライズ処理が実行される前です。

パラメータ

• in

  シリアル化された文字列。

返り値

フィルタ処理したシリアル化された文字列。

MessagePacki_Filter::post_unserialize — アンシリアライズ処理後にコールされる

説明

public mixed MessagePacki_Filter::post_unserialize ( mixed $in )

このメソッドがコールされるのは、アンシリアライズ処理が実行た後です。

パラメータ

• in

  アンシリアライズ処理された値。

返り値

フィルタ処理したアンシリアライズ処理された値。

名前空間関数

名前空間は「MessagePacki」になります。

一覧

• MessagePacki\serialize

  msgpacki_serialize() 関数のエイリアス

• MessagePacki\unserialize

  msgpacki_unserialize() 関数のエイリアス

• MessagePacki\encode

  msgpacki_encode() 関数のエイリアス

• MessagePacki\decode

  msgpacki_decode() 関数のエイリアス

• MessagePacki\filter_register

  msgpacki_filter_register() 関数のエイリアス

• MessagePacki\filter_append

  msgpacki_filter_append() 関数のエイリアス

• MessagePacki\filter_prepend

  msgpacki_filter_prepend() 関数のエイリアス

• MessagePacki\filter_remove

  msgpacki_filter_remove() 関数のエイリアス

• MessagePacki\msgpacki_filter_get_filters

  msgpacki_filter_get_filters() 関数のエイリアス

名前空間クラス関数

名前空間は「MessagePacki」になります。

一覧

• MessagePacki\Filter

  MessagePacki_Filter クラスのエイリアス

セッションシリアライズ

session.serialize_handler として MessagePack フォーマットをサポートします。

session.serialize_handler string

msgpacki を指定することで MessagePack フォーマットでセッション値のシリアライズ処 理します。

この時の動作モード MSGPACKI_MODE_PHP になります。

フィルターはサポートしておりません。

開発環境

• PHP 5.4.4 / 5.4.7 / 5.4.8
• Fedora 16 / 17 (x86_64)

検証

検証した環境およびバージョンは次の通りです。

バージョン: 1.1.0

• PHP 5.4.8 on Fedora 17 (x86_64)
• PHP 5.4.8 [ZTS] on Fedora 16 (x86_64)
• PHP 5.4.8 on Windows Vista Home Premium SP2 (32 bit)
• PHP 5.4.8 [nts] on Windows Vista Home Premium SP2 (32 bit)
• PHP 5.4.13 on Fedora 17 (x86_64)
• PHP 5.4.13 on Windows Vista Home Premium SP2 (32 bit)
• PHP 5.4.13 [nts] on Windows Vista Home Premium SP2 (32 bit)

バージョン: 1.0.1

• PHP 5.4.7 on Fedora 17 (x86_64)
• PHP 5.4.7 [ZTS] on Fedora 16 (x86_64)
• PHP 5.4.7 on Windows Vista Home Premium SP2 (32 bit)
• PHP 5.4.7 [nts] on Windows Vista Home Premium SP2 (32 bit)

バージョン: 1.0.0

• PHP 5.2.17 on Fedora 16 (x86_64)
• PHP 5.2.17 [ZTS] on Fedora 16 (x86_64)
• PHP 5.3.14 on Fedora 16 (x86_64)
• PHP 5.3.14 [ZTS] on Fedora 16 (x86_64)
• PHP 5.4.4 on Fedora 16 (x86_64)
• PHP 5.4.4 [ZTS] on Fedora 16 (x86_64)
• PHP 5.4.4 on Fedora 17 (i686) [KVM]
• PHP 5.4.4 on Windows Vista Home Premium SP2 (32 bit)
• PHP 5.4.4 [nts] on Windows Vista Home Premium SP2 (32 bit)

関連ページ

• code coverage report
• api document
• Windows Binary