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

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

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

• 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

リリースごとのコンパイル済みバイナリがにあります。 アーカイブを 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 の設定により動作が変化します。

• デフォルト: 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 — フィルタのリストを取得する

string msgpacki_serialize ( mixed $value )

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

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

• value

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

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

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

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

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

• str

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

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

• status

  処理の成否結果。

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

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

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

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

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

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

• value

  シリアル化する値。

• options

  動作モード。

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

基本的に 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 を発生します。

bool msgpacki_filter_register ( string $filtername , string $classname )

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

• filtername

  登録するフィルタ名。

• classname

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

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

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

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

bool msgpacki_filter_append ( string $filtername )

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

• filtername

  フィルタ名。

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

bool msgpacki_filter_prepend ( string $filtername )

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

• filtername

  フィルタ名。

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

bool msgpacki_filter_remove ( string $filtername )

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

• filtername

  フィルタ名。

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

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 {
    /* メソッド */
    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 — フィルタのリストを取得する

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

• mode

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

  既定値は MSGPACKI_MODE_PHP。

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

public string MessagePacki::pack ( mixed $value )

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

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

• value

  シリアル化する値。

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

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

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

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

• str

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

• status

  処理の成否結果。

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

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

public int MessagePacki::get_mode ()

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

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

public bool MessagePacki::set_mode ( int $mode )

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

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

• mode

  動作モード値。

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

public bool MessagePacki::append_filter ( string $name )

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

• name

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

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

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

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

public bool MessagePacki::prepend_filter ( string $name )

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

• name

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

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

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

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

public bool MessagePacki::remove_filter ( string $name )

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

• name

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

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

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

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

• type

  フィルタタイプ。

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

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

このクラスの子クラスを 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 — アンシリアライズ処理後に実行される

public mixed MessagePacki_Filter::pre_serialize ( mixed $in )

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

• in

  シリアライズ化する値。

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

public string MessagePacki_Filter::pre_serialize ( string $in )

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

• in

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

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

public string MessagePacki_Filter::pre_unserialize ( string $in )

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

• in

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

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

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 フォーマットをサポートします。

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

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

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

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

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

• 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)

• 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)

• 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