stream_socket_shutdown
"for use with all the other filesystem functions"
"all" is not accurate. Unfortunately, zip_open(), and presumably others, will ignore your custom stream wrapper.
stream_wrapper_register
(PHP 4 >= 4.3.2, PHP 5)
stream_wrapper_register — PHP のクラスとして実装された URL ラッパを登録する
説明
bool stream_wrapper_register
( string $protocol
, string $classname
)
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 を返します。
bool stream_open
( string $path
, string $mode
, int $options
, string $opened_path
)
このメソッドは、ストリームオブジェクトが生成された直後に呼び出されます。 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 を返さなくてはなりません。
void stream_close
( void
)
このメソッドは、fclose()によってストリームが閉じられるときに呼び出されます。 この時点で、カスタムストリームの中でロックされたか確保されたリソースを 開放しなくてはなりません。
string stream_read
( int $count
)
このメソッドはカスタムストリームに対する fread() または fgets() に対応して呼び出されます。 count バイトを超えない長さのデータが返される ようにする必要があります。 count バイトよりも少ないデータしか準備できていない 場合は、その時点にあるだけを返します。もし渡すべきデータがもうなければ、 FALSE または空文字列を返してください。 また、正常に読み込めた分だけ、ストリームの読み込み/書き出し操作における 内部位置を更新しなくてはなりません。
int stream_write
( string $data
)
このメソッドは、カスタムストリームに対する fwrite() などの 書き出し動作に対応して呼び出されます。data には、 カスタムストリームで使われている下層にあるストレージに書き出されるべき データが入っています。渡されたデータをすべて書き出せない場合は、 書き出せるだけ書き出します。このとき、正常にデータを書き出せた場合は、 その書き出せたバイト数を、書き出せなかった場合は 0 を返さなくては なりません。 また、正常に読み込めた分だけ、ストリームの読み込み/書き出し操作における 内部位置を更新しなくてはなりません。
bool stream_eof
( void
)
このメソッドは、ストリームに対する feof() 関数の実行に 対応して呼び出されます。 もし、ストリームの読み込み/書き出し操作における内部位置が、 ストリームの終端にある場合は、あるいは、もう読み込むべきデータがない 場合は TRUE を、その他の場合には FALSE をそれぞれ返さなくては なりません。
int stream_tell
( void
)
このメソッドは、ストリームに対する ftell() 関数の 実行に対応して呼び出されます。 ストリームの読み込み/書き出し操作における内部位置を返します。
bool stream_seek
( int $offset
, int $whence
)
このメソッドは、ストリームに対する fseek() 関数の 実行に対応して呼び出されます。 ストリームの読み込み/書き出し操作における内部位置を、 offset パラメータと whence パラメータの値に従って更新しなければなりません。 なお、これらの値の取り方については、fseek() を参照ください。 正常に位置が更新できた場合には TRUE を、失敗した場合は FALSE を返します。
bool stream_flush
( void
)
このメソッドは、ストリームに対する fflush() 関数の 実行に対応して呼び出されます。 もしカスタムストリームがデータをキャッシュしていて、 それをまだ下層にあるストレージへ記録していない場合は、 このメソッドが呼ばれた時に、それを書き出します。 もしキャッシュされたデータが正常に書き出された (あるいは、もう書くべきデータ がない) 場合は、TRUE を、もしくは、データを書き出すことができなかった 場合は FALSE を返します。
array stream_stat
( void
)
このメソッドは、ストリームに対する fstat() 関数の 実行に対応して呼び出されます。 fstat() が返すのと同じような要素をもつ配列に、 適切な値を入れて返さなくてはなりません。
このメソッドは、ラッパに関連付けられた 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 以前ではサポートされていません。
bool dir_opendir
( string $path
, int $options
)
このメソッドは、ディレクトリの内容を走査するために、 ストリームオブジェクトが opendir()によって 生成されるその時に呼び出されます。 path は、opendir() に 渡された、このオブジェクトが走査すべき場所を示す URL を指定します。 このとき、parse_url() を使えば、この URL を 細分することができます。
array url_stat
( string $path
, int $flags
)
このメソッドは、ラッパに関連付けられた URL のパスに対する stat() 関数の実行に対応して呼び出され、 システムの関数が返す要素とできるだけ同じ内容を返さなければなりません。 不明な、あるいは取得できない値には、妥当な値を設定しておくべきです （通常は 0 です）。
flags には、ストリーム API によって設定された 追加のフラグを保持します。以下のうちのひとつまたは複数を OR で結合した 値を保持します。
| フラグ | 説明 |
|---|---|
| STREAM_URL_STAT_LINK | 他のリソースへのリンク機能があるリソース（たとえば HTTP の Location: forward やファイルシステムのシンボリック リンクなど）。このフラグはリンクそのものについての情報のみを 返し、リンクが指している先のリソースについては返しません。 このフラグは lstat()、 is_link() あるいは filetype() のコールへの応答として設定されます。 |
| STREAM_URL_STAT_QUIET | このフラグが設定されている場合、ラッパは一切エラーを 報告してはいけません。このフラグが設定されていない場合は、 パスを調べている間に発生したエラーについて trigger_error() で報告する義務があります。 |
string dir_readdir
( void
)
このメソッドは、readdir() 関数の呼び出しに 対応して呼ばれます。dir_opendir() メソッドにおいて 指定された場所にあるファイルのリスト上の、次のファイル名を表す 文字列を返さなくてはなりません。
bool dir_rewinddir
( void
)
このメソッドは、rewinddir() 関数の呼び出しに 対応して呼ばれます。このとき、dir_readdir() メソッドにおいて変更された状態をリセットしなくてはなりません。 つまり、このメソッドの呼び出しに続いて dir_readdir() が 呼ばれると、dir_opendir() によって開かれた ファイルのリスト上の、最初のエントリを返すことになります。
bool dir_closedir
( void
)
このメソッドは、closedir() 関数の呼び出しに 対応して呼ばれます。このとき、ディレクトリストリームの利用に際して 確保されたりロックされたリソースを全て開放しなければなりません。
下記の例は、var:// プロトコルハンドラを実装し、 fread() などの標準のファイルシステム関数 を利用して、指定されたグローバル変数に対するアクセスができるように するものです。 var:// プロトコルは、"var://foo" として与えられた URL に対応して、 $GLOBALS["foo"] からデータを読み込んだり、そこにデータを書き込んだり します。
例1 グローバル変数を読み書きするストリーム
<?php
class VariableStream {
var $position;
var $varname;
function stream_open($path, $mode, $options, &$opened_path)
{
$url = parse_url($path);
$this->varname = $url["host"];
$this->position = 0;
return true;
}
function stream_read($count)
{
$ret = substr($GLOBALS[$this->varname], $this->position, $count);
$this->position += strlen($ret);
return $ret;
}
function stream_write($data)
{
$left = substr($GLOBALS[$this->varname], 0, $this->position);
$right = substr($GLOBALS[$this->varname], $this->position + strlen($data));
$GLOBALS[$this->varname] = $left . $data . $right;
$this->position += strlen($data);
return strlen($data);
}
function stream_tell()
{
return $this->position;
}
function stream_eof()
{
return $this->position >= strlen($GLOBALS[$this->varname]);
}
function stream_seek($offset, $whence)
{
switch ($whence) {
case SEEK_SET:
if ($offset < strlen($GLOBALS[$this->varname]) && $offset >= 0) {
$this->position = $offset;
return true;
} else {
return false;
}
break;
case SEEK_CUR:
if ($offset >= 0) {
$this->position += $offset;
return true;
} else {
return false;
}
break;
case SEEK_END:
if (strlen($GLOBALS[$this->varname]) + $offset >= 0) {
$this->position = strlen($GLOBALS[$this->varname]) + $offset;
return true;
} else {
return false;
}
break;
default:
return false;
}
}
}
stream_wrapper_register("var", "VariableStream")
or die("プロトコルの登録に失敗しました");
$myvar = "";
$fp = fopen("var://myvar", "r+");
fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");
rewind($fp);
while (!feof($fp)) {
echo fgets($fp);
}
fclose($fp);
var_dump($myvar);
?>
add a note
User Contributed Notesstream_wrapper_register
Anonymous
16-Sep-2008 11:19
16-Sep-2008 11:19
phrank
17-Apr-2008 01:38
17-Apr-2008 01:38
Actually, I don't know if there's a better way to figure out if stream_read() was called by fgets() or e.g. fread() than this one:
public function stream_read($count)
{
$bt = debug_backtrace();
if(($bt[0]['function'] == 'stream_read') &&
($bt[1]['function'] == 'fgets'))
{
$pos = strpos($GLOBALS[$this->varname], "\n", $this->position);
$retval = substr($GLOBALS[$this->varname], $this->position, ($pos > $count) ? $count : $pos+1);
}
else
{
$retval = substr($GLOBALS[$this->varname], $this->position, $count);
}
$this->position += strlen($retval);
return (string)$retval;
}
Rick Hodger
20-Dec-2007 03:47
20-Dec-2007 03:47
I have created a POP3 stream wrapper, available at http://www.potato-people.com/code/pop3.stream/
yeiniel at gmail dot com
14-Oct-2007 07:30
14-Oct-2007 07:30
on using dir_opendir on PHP5 make sure you not return a resource object on success. A resource object is diferent from false but php make a cast to bool to dir_opendir return value and modify the value of your resource to 1.
example:
class myclass{
private $mysqlHandler;
public function dir_opendir(....)
{
$this->mysqlHandler = mysql_connect(....);
return $this->mysqlHandler; //this is wrong, next
//time you use
//$this->mysqlHandler
// the value is 1
}
}
vmvarela at gmail dot com
24-Sep-2007 09:34
24-Sep-2007 09:34
I have written a new SMB Stream Wrapper for Unix systems using smbclient (SAMBA project).
http://freshmeat.net/smb4php
fordiman at gmail dot com
13-Aug-2007 05:59
13-Aug-2007 05:59
Updated. I figured there's no need to store the variable name if we're dereferenceing; we can just store the pointer and not have to dereference in each function for brevity.
Also, I added the assertion that the stream is a string, since we're behaving basically like it has to be, and I changed the name to GlobalStream and global://, as that's a more descriptive moniker than VariableName/var://.
<?php
class GlobalStream {
private $pos;
private $stream;
public function stream_open($path, $mode, $options, &$opened_path) {
$url = parse_url($path);
$this->stream = &$GLOBALS[$url["host"]];
$this->pos = 0;
if (!is_string($this->stream)) return false;
return true;
}
public function stream_read($count) {
$p=&$this->pos;
$ret = substr($this->stream, $this->pos, $count);
$this->pos += strlen($ret);
return $ret;
}
public function stream_write($data){
$l=strlen($data);
$this->stream =
substr($this->stream, 0, $this->pos) .
$data .
substr($this->stream, $this->pos += $l);
return $l;
}
public function stream_tell() {
return $this->pos;
}
public function stream_eof() {
return $this->pos >= strlen($this->stream);
}
public function stream_seek($offset, $whence) {
$l=strlen($this->stream);
switch ($whence) {
case SEEK_SET: $newPos = $offset; break;
case SEEK_CUR: $newPos = $this->pos + $offset; break;
case SEEK_END: $newPos = $l + $offset; break;
default: return false;
}
$ret = ($newPos >=0 && $newPos <=$l);
if ($ret) $this->pos=$newPos;
return $ret;
}
}
stream_wrapper_register('global', 'GlobalStream') or die('Failed to register protocol global://');
$myvar = "";
$fp = fopen("global://myvar", "r+");
fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");
rewind($fp);
while (!feof($fp)) {
echo fgets($fp);
}
fclose($fp);
var_dump($myvar);
?>
fordiman at gmail dot com
13-Aug-2007 05:32
13-Aug-2007 05:32
Updated for PHP 5, and optimized for readability, low line count, and minimum memory use:
<?php
class VariableStream {
private $position;
private $varname;
public function stream_open($path, $mode, $options, &$opened_path) {
$url = parse_url($path);
$this->varname = $url["host"];
$this->position = 0;
return true;
}
public function stream_read($count) {
$p=&$this->position;
$ret = substr($GLOBALS[$this->varname], $p, $count);
$p += strlen($ret);
return $ret;
}
public function stream_write($data){
$v=&$GLOBALS[$this->varname];
$l=strlen($data);
$p=&$this->position;
$v = substr($v, 0, $p) . $data . substr($v, $p += $l);
return $l;
}
public function stream_tell() {
return $this->position;
}
public function stream_eof() {
return $this->position >= strlen($GLOBALS[$this->varname]);
}
public function stream_seek($offset, $whence) {
$l=strlen(&$GLOBALS[$this->varname]);
$p=&$this->position;
switch ($whence) {
case SEEK_SET: $newPos = $offset; break;
case SEEK_CUR: $newPos = $p + $offset; break;
case SEEK_END: $newPos = $l + $offset; break;
default: return false;
}
$ret = ($newPos >=0 && $newPos <=$l);
if ($ret) $p=$newPos;
return $ret;
}
}
stream_wrapper_register("var", "VariableStream")
or die("Failed to register protocol");
$myvar = "";
$fp = fopen("var://myvar", "r+");
fwrite($fp, "line1\n");
fwrite($fp, "line2\n");
fwrite($fp, "line3\n");
rewind($fp);
while (!feof($fp)) {
echo fgets($fp);
}
fclose($fp);
var_dump($myvar);
?>
phpnet at povaddict dot com dot ar
09-Jun-2007 08:10
09-Jun-2007 08:10
In response to Anonymouse at Coward dot com:
The manual says "Reading stops when up to length bytes have been read, [...] or (after opening userspace stream) when 8192 bytes have been read whichever comes first."
I tested it and fread($filehandle, 4096) returns 4096 bytes, so it's working as the manual says it should. You're right when you say "8192 bytes is always passed to stream_read as count", but that doesn't mean fread will return 8192 bytes. If you call fread twice with length 4096, PHP calls stream_read passing 8192 as count on the first fread, and doesn't call it on second fread. On both cases, fread returns the correct amount of bytes.
<?php
class VariableStream {
var $position;
var $varname;
function stream_open($path, $mode, $options, &$opened_path)
{
$url = parse_url($path);
$this->varname = $url["host"];
$this->position = 0;
return true;
}
function stream_read($count)
{
echo "stream_read called asking for $count bytes\n";
$ret = substr($GLOBALS[$this->varname], $this->position, $count);
$this->position += strlen($ret);
return $ret;
}
function stream_eof()
{
return $this->position >= strlen($GLOBALS[$this->varname]);
}
}
stream_wrapper_register("var", "VariableStream")
or die("Failed to register protocol");
$myvar = "";
$l=range('a','z');
for($i=0;$i<65536;$i++) {
$myvar .= $l[array_rand($l)];
}
$fp = fopen("var://myvar", "r+");
while (!feof($fp)) {
$out = fread($fp,1000);
echo "fread returned ",strlen($out)," bytes\n";
}
fclose($fp);
?>
Anonymouse at Coward dot com
26-Apr-2007 09:18
26-Apr-2007 09:18
Use caution with writing code that may use stream wrappers with fread, as fread behaviour is 'inconsistent' with normal file operations because of the 8192 bytes internal buffer used by PHP ( >= 5.0.5 IIRC ).
ie:
fread($filehandle, filesize($filename))
will not work correctly if the file is larger than 8KB, it will only get you the first 8192 bytes. Also, it seems that:
fread($filehandle, 4096)
will still give you 8KB (if the file is larger than 8KB) as 8192 bytes is always passed to stream_read as count.
This makes it somewhat impossible to just 'drop in' a stream where normally a file would be used without taking special care.
Yes, it IS mentioned in the documentation here if you read it really well, but I for one spent some time scratching my head over it, and looking at the bug tracker, I am not the only one. The dev's say this inconsistancy is a feature though, even if it does make stream wrappers pretty much useless 'out of the box'.
file_get_contents and stream_get_contents seem to work ok though.
none at your dot biz
09-Nov-2006 04:35
09-Nov-2006 04:35
In case someone else starts scratching their head like I was, you should change the VariableStream::stream_eof() function to something like this:
function stream_eof()
{
$eof = ($this->position >= strlen($GLOBALS[$this->varname]));
if(version_compare(PHP_VERSION,'5.0','>=') && version_compare(PHP_VERSION,'5.1','<'))
{
$eof = !$eof;
}
return $eof;
}
PHP 5.0 introduced a bug that wasn't fixed until 5.1
jhannus at php dot net
20-Jun-2005 07:37
20-Jun-2005 07:37
It is worth noting that if your wrapper supports stream_flush() then when you flcose() your stream this function will be called prior to closing the stream.
cellog at php dot net
12-Apr-2005 07:45
12-Apr-2005 07:45
If you plan to use your wrapper in a require_once you need to define stream_stat(). If you plan to allow any other tests like is_file()/is_dir(), you have to define url_stat().
stream_stat() must define the size of the file, or it will never be included. url_stat() must define mode, or is_file()/is_dir()/is_executable(), and any of those functions affected by clearstatcache() simply won't work.
It's not documented, but directories must be a mode like 040777 (octal), and files a mode like 0100666. If you wish the file to be executable, use 7s instead of 6s. The last 3 digits are exactly the same thing as what you pass to chmod. 040000 defines a directory, and 0100000 defines a file. It would be really helpful to add this to the official manual!
Hayley Watson
03-Apr-2005 11:07
03-Apr-2005 11:07
The current URL standard is RFC 3986 - available at www.ietf.org/rfc/rfc3986.txt
simon at firepages dot org
13-Apr-2004 10:53
13-Apr-2004 10:53
using streams to use the ever useful fgetcsv() on a variable where explode() would not work (and would otherwise require regex(though that may be easier;)))
$explode_this="yak, llama, 'big llama', 'wobmat, with a comma in it', bandycoot";
<?php
class csvstream{
var $position;
var $varname;
function stream_open($path, $mode, $options, &$opened_path){
$url = parse_url($path);
$this->varname = $url['host'] ;
$this->position = 0;
return true;
}
function stream_read($count){
$ret = substr($GLOBALS[$this->varname], $this->position, $count);
$this->position += strlen($ret);
return $ret;
}
function stream_eof(){
return $this->position >= strlen($GLOBALS[$this->varname]);
}
function stream_tell(){
return $this->position;
}
}
stream_wrapper_register("csvstr", "csvstream") ;
$str="yak, llama, 'big llama', 'wobmat, with a comma in it', bandycoot";
$fp = fopen("csvstr://str", "r+");
print_r(fgetcsv($fp,100,",","'"));
?>