stream_wrapper_register

説明

stream_wrapper_register() は、自分で作った プロトコルハンドラとストリームを実装し、それを fopen() や fread() といったファイルシステムの関数と利用することを可能にします。

ラッパを実装するには、下記のようないくつかのメンバ関数を持った クラスを定義しなくてはなりません。もし、誰かがあなたの作った ストリームを fopen() したとき、 PHP は classname のインスタンスを作り 以後そのインスタンスと共にメソッドを呼び出そうとします。 これらのメソッドは、下記に示したとおり、正確に実装されなければなりません。 さもないと、定義されていない動作をします。

注意: PHP 5.0.0 より新たに、classname のインスタンス内の context プロパティが、 コンテキストリソース を参照する形で 初期化されるようになります。なお、 この コンテキストリソースは、 stream_context_get_options() によっても 取得することができます。 もし、コンテキストがストリーム生成関数に対し渡されていない場合は、 context の値は NULL にセットされます。

stream_wrapper_register() は、 protocol というハンドラが既にある場合、 FALSE を返します。

このメソッドは、ストリームオブジェクトが生成された直後に呼び出されます。 path には、fopen() に 与えられ、データの取得元となる URL が入ります。 parse_url() を使えば、この URL を解釈できます。

mode は、ファイルを開く際に使われるモードです。 fopen() で詳しく述べられているように、 この関数の側で、mode が要求された path に適切かどうかを調べなくてはなりません。

options は、ストリーム API によってセットされる 付加的なフラグです。この値は次に挙げた値のいずれかか、 それらを二つ以上 OR 演算した値となります。

フラグ	説明
STREAM_USE_PATH	もし path が相対パスだった場合、 include_path で指定されたパス内を探索します。
STREAM_REPORT_ERRORS	このフラグがセットされている場合は、ストリームのオープン時に ラッパ側で trigger_error() 関数を使い、エラーを 発生させる必要があります。逆に、このフラグがセットされていない場合は、 ラッパ側でエラーを発生させてはいけません。

もし path に対するストリームのオープンに成功し、 STREAM_USE_PATH が options にセットされていた 際には、opened_path に、実際に開かれた ファイルまたはリソースへの絶対パスをセットしなくてはなりません。

もし要求されたリソースを正常に開けた場合、TRUE を、そうでなければ、 FALSE を返さなくてはなりません。

このメソッドは、fclose()によってストリームが閉じられるときに呼び出されます。 この時点で、カスタムストリームの中でロックされたか確保されたリソースを 開放しなくてはなりません。

このメソッドはカスタムストリームに対する fread() または fgets() に対応して呼び出されます。 count バイトを超えない長さのデータが返される ようにする必要があります。 count バイトよりも少ないデータしか準備できていない 場合は、その時点にあるだけを返します。もし渡すべきデータがもうなければ、 FALSE または空文字列を返してください。 また、正常に読み込めた分だけ、ストリームの読み込み/書き出し操作における 内部位置を更新しなくてはなりません。

このメソッドは、カスタムストリームに対する fwrite() などの 書き出し動作に対応して呼び出されます。data には、 カスタムストリームで使われている下層にあるストレージに書き出されるべき データが入っています。渡されたデータをすべて書き出せない場合は、 書き出せるだけ書き出します。このとき、正常にデータを書き出せた場合は、 その書き出せたバイト数を、書き出せなかった場合は 0 を返さなくては なりません。 また、正常に読み込めた分だけ、ストリームの読み込み/書き出し操作における 内部位置を更新しなくてはなりません。

このメソッドは、ストリームに対する feof() 関数の実行に 対応して呼び出されます。 もし、ストリームの読み込み/書き出し操作における内部位置が、 ストリームの終端にある場合は、あるいは、もう読み込むべきデータがない 場合は TRUE を、その他の場合には FALSE をそれぞれ返さなくては なりません。

このメソッドは、ストリームに対する ftell() 関数の 実行に対応して呼び出されます。 ストリームの読み込み/書き出し操作における内部位置を返します。

このメソッドは、ストリームに対する fseek() 関数の 実行に対応して呼び出されます。 ストリームの読み込み/書き出し操作における内部位置を、 offset パラメータと whence パラメータの値に従って更新しなければなりません。 なお、これらの値の取り方については、fseek() を参照ください。 正常に位置が更新できた場合には TRUE を、失敗した場合は FALSE を返します。

このメソッドは、ストリームに対する fflush() 関数の 実行に対応して呼び出されます。 もしカスタムストリームがデータをキャッシュしていて、 それをまだ下層にあるストレージへ記録していない場合は、 このメソッドが呼ばれた時に、それを書き出します。 もしキャッシュされたデータが正常に書き出された (あるいは、もう書くべきデータ がない) 場合は、TRUE を、もしくは、データを書き出すことができなかった 場合は FALSE を返します。

このメソッドは、ストリームに対する fstat() 関数の 実行に対応して呼び出されます。 fstat() が返すのと同じような要素をもつ配列に、 適切な値を入れて返さなくてはなりません。

このメソッドは、ストリーム上での stream_select() に対応してコールされ、ラッパーが使用するストリームリソースあるいは FALSE を返します。 cast_as パラメータは、 stream_select() が stream_cast() をコールした場合は STREAM_CAST_FOR_SELECT となり、 stream_cast() がそれ以外からコールされた場合は STREAM_CAST_AS_STREAM となります。

注意: ユーザ空間のラッパーメソッド stream_cast は、 PHP 5.3.0 より前のバージョンではサポートされていません。

このメソッドは、オプションをストリームに設定する際にコールされます。 option に設定できる値は次のとおりです。

• STREAM_OPTION_BLOCKING: このメソッドは stream_set_blocking() に対応してコールされます。 arg1 はブロックモードです。
• STREAM_OPTION_READ_TIMEOUT: このメソッドは stream_set_timeout() に対応してコールされます。 arg1 はタイムアウトの秒数、 arg2 はタイムアウトのマイクロ秒数です。
• STREAM_OPTION_WRITE_BUFFER: このメソッドは stream_set_write_buffer() に対応してコールされます。 arg1 はバッファモード (STREAM_BUFFER_NONE あるいは STREAM_BUFFER_FULL)、arg2 はバッファサイズです。

stream_set_option() は、失敗した場合あるいは option が実装されていない場合に FALSE、 それ以外の場合に TRUE を返さなければなりません。

注意: ユーザ空間のラッパーメソッド stream_set_option は、 PHP 5.3.0 より前のバージョンではサポートされていません。

このメソッドは、ラッパに関連付けられた URL のパスに対する unlink() 関数の実行に対応して呼び出されます。 path で指定されたパスにあるアイテムを 削除しようと試みなければなりません。その時、削除に成功したら TRUE を、失敗したら FALSE を返してください。 適切なエラーメッセージがユーザに返されるよう、ラッパ側で削除を サポートしない場合は、このメソッドを定義しないでください。

注意: ユーザ定義のラッパにおける unlink メソッドは、 PHP 5.0.0 以前ではサポートされていません。

このメソッドは、ラッパに関連付けられた URL のパスに対する rename() 関数の実行に対応して呼び出され、 path_from で指定されたパスにある項目を path_to にリネームすることを試みなければなりません。 成功した場合に TRUE、失敗した場合に FALSE を返さなければなりません。 適切なエラーメッセージが返されるよう、ラッパ側でリネームをサポートしない 場合はこのメソッドを定義しないでください。

注意: ユーザ定義のラッパにおける rename メソッドは、 PHP 5.0.0 以前ではサポートされていません。

このメソッドは、ラッパに関連付けられた URL のパスに対する mkdir() 関数の実行に対応して呼び出され、 path で指定されたディレクトリの作成を 試みなければなりません。 成功した場合に TRUE、失敗した場合に FALSE を返さなければなりません。 適切なエラーメッセージが返されるよう、ラッパ側でディレクトリの作成を サポートしない場合はこのメソッドを定義しないでください。 options でとりうる値には STREAM_REPORT_ERRORS および STREAM_MKDIR_RECURSIVE が含まれます。

注意: ユーザ定義のラッパにおける mkdir メソッドは、 PHP 5.0.0 以前ではサポートされていません。

このメソッドは、ラッパに関連付けられた URL のパスに対する rmdir() 関数の実行に対応して呼び出され、 path で指定されたディレクトリの削除を 試みなければなりません。 成功した場合に TRUE、失敗した場合に FALSE を返さなければなりません。 適切なエラーメッセージが返されるよう、ラッパ側でディレクトリの削除を サポートしない場合はこのメソッドを定義しないでください。 options でとりうる値には STREAM_REPORT_ERRORS が含まれます。

注意: ユーザ定義のラッパにおける rmdir メソッドは、 PHP 5.0.0 以前ではサポートされていません。

このメソッドは、ディレクトリの内容を走査するために、 ストリームオブジェクトが opendir()によって 生成されるその時に呼び出されます。 path は、opendir() に 渡された、このオブジェクトが走査すべき場所を示す URL を指定します。 このとき、parse_url() を使えば、この URL を 細分することができます。

このメソッドは、ラッパに関連付けられた URL のパスに対する stat() 関数の実行に対応して呼び出され、 システムの関数が返す要素とできるだけ同じ内容を返さなければなりません。 不明な、あるいは取得できない値には、妥当な値を設定しておくべきです （通常は 0 です）。

flags には、ストリーム API によって設定された 追加のフラグを保持します。以下のうちのひとつまたは複数を OR で結合した 値を保持します。

フラグ	説明
STREAM_URL_STAT_LINK	他のリソースへのリンク機能があるリソース（たとえば HTTP の Location: forward やファイルシステムのシンボリック リンクなど）。このフラグはリンクそのものについての情報のみを 返し、リンクが指している先のリソースについては返しません。 このフラグは lstat()、 is_link() あるいは filetype() のコールへの応答として設定されます。
STREAM_URL_STAT_QUIET	このフラグが設定されている場合、ラッパは一切エラーを 報告してはいけません。このフラグが設定されていない場合は、 パスを調べている間に発生したエラーについて trigger_error() で報告する義務があります。

このメソッドは、readdir() 関数の呼び出しに 対応して呼ばれます。dir_opendir() メソッドにおいて 指定された場所にあるファイルのリスト上の、次のファイル名を表す 文字列を返さなくてはなりません。

このメソッドは、rewinddir() 関数の呼び出しに 対応して呼ばれます。このとき、dir_readdir() メソッドにおいて変更された状態をリセットしなくてはなりません。 つまり、このメソッドの呼び出しに続いて dir_readdir() が 呼ばれると、dir_opendir() によって開かれた ファイルのリスト上の、最初のエントリを返すことになります。

このメソッドは、closedir() 関数の呼び出しに 対応して呼ばれます。このとき、ディレクトリストリームの利用に際して 確保されたりロックされたリソースを全て開放しなければなりません。

下記の例は、var:// プロトコルハンドラを実装し、 fread() などの標準のファイルシステム関数 を利用して、指定されたグローバル変数に対するアクセスができるように するものです。 var:// プロトコルは、"var://foo" として与えられた URL に対応して、 $GLOBALS["foo"] からデータを読み込んだり、そこにデータを書き込んだり します。