SunshinePHP Developer Conference 2015

stream_register_wrapper

(PHP 4 >= 4.3.0, PHP 5)

stream_register_wrapper注册一个用 PHP 类实现的 URL 封装协议

说明

boolean stream_register_wrapper ( string $protocol , string $classname )

stream_register_wrapper() 允许用户实现自定义的协议处理器和流,用于所有其它的文件系统函数中(例如 fopen()fread() 等)。

要实现一个封装协议,需要按照如下定义声明一个包含有一些函数的类。当有人对你的流使用 fopen 时,PHP 将创建一个 classname 的实例并调用该实例的方法。必须严格按照如下的描述实现方法 - 否则将导致不明确的行为。

如果 protocol 已经有了处理协议,则 stream_register_wrapper() 将返回 FALSE

boolean 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,并且在 options 中设定了 STREAM_USE_PATH,你需要将 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。必须用成功写入的字节数去更新流的读写位置。

boolean stream_eof ( void )

当对流进行 feof() 操作时本方法被调用。如果读写位置到了流的尽头或者没有更多数据可读时返回 TRUE,否则返回 FALSE

int stream_tell ( void )

当对流进行 ftell() 操作时本方法被调用。应该返回流的当前读写位置。

boolean stream_seek ( int $offset , int $whence )

当对流进行 fseek() 操作时本方法被调用。应该根据 offsetwhence 来更新流的读写位置。这些参数的更多信息见 fseek()。如果位置成功更新了则返回 TRUE,否则返回 FALSE

boolean stream_flush ( void )

当对流进行 fflush() 操作时本方法被调用。如果你在流中缓存了数据还没有写入底层存储空间时,那现在应该做了。如果缓存数据被成功保存(或没有数据可供保存)时返回 TRUE,当数据无法被保存时返回 FALSE

下面的例子实现了一个 var:// 协议处理器,可以允许使用标准的文件系统流函数来对指定的全局变量进行读写操作,例如 fread()。var:// 协议的实现如下,给出 url "var://foo" 将可以读写 $GLOBALS["foo"]。

Example #1 读写全局变量的流

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_register_wrapper("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);

add a note add a note

User Contributed Notes 13 notes

up
4
fordiman at gmail dot com
7 years ago
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);
?>
up
2
Anonymouse at Coward dot com
7 years ago
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.
up
2
cellog at php dot net
9 years ago
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!
up
1
Anonymous
6 years ago
"for use with all the other filesystem functions"

"all" is not accurate.  Unfortunately, zip_open(), and presumably others, will ignore your custom stream wrapper.
up
0
dmarjos at gmail dot com
1 year ago
Be aware that even when stream_wrapper_register won't fail, open_basedir will affect functionality of the class.
up
0
phrank
6 years ago
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;
    }
up
0
yeiniel at gmail dot com
7 years ago
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
  }
}
up
0
fordiman at gmail dot com
7 years ago
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);
?>
up
0
phpnet at povaddict dot com dot ar
7 years ago
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);

?>
up
0
none at your dot biz
7 years ago
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
up
0
Hayley Watson
9 years ago
The current URL standard is RFC 3986 - available at www.ietf.org/rfc/rfc3986.txt
up
0
simon at firepages dot org
10 years ago
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,",","'"));

?>
up
-1
jhannus at php dot net
9 years ago
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.
To Top