Delicious Bookmark this on Delicious Share on Facebook SlashdotSlashdot It! Digg! Digg



PHP : Function Reference : Stream Functions : stream_wrapper_register

stream_wrapper_register

Register a URL wrapper implemented as a PHP class (PHP 4 >= 4.3.2, PHP 5)
bool stream_wrapper_register ( string protocol, string classname )
bool stream_open ( string path, string mode, int options, string opened_path )
void stream_close ( )
string stream_read ( int count )
int stream_write ( string data )
bool stream_eof ( )
int stream_tell ( )
bool stream_seek ( int offset, int whence )
bool stream_flush ( )
array stream_stat ( )
bool unlink ( string path )
bool rename ( string path_from, string path_to )
bool mkdir ( string path, int mode, int options )
bool rmdir ( string path, int options )
bool dir_opendir ( string path, int options )
array url_stat ( string path, int flags )
string dir_readdir ( )
bool dir_rewinddir ( )
bool dir_closedir ( )

stream_wrapper_register() allows you to implement your own protocol handlers and streams for use with all the other filesystem functions (such as fopen(), fread() etc.).

To implement a wrapper, you need to define a class with a number of member functions, as defined below. When someone fopens your stream, PHP will create an instance of classname and then call methods on that instance. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour.

Note:

As of PHP 5.0.0 the instance of classname will be populated with a context property referencing a Context Resource which may be accessed with stream_context_get_options(). If no context was passed to the stream creation function, context will be set to NULL.

stream_wrapper_register() will return FALSE if the protocol already has a handler.

This method is called immediately after your stream object is created. path specifies the URL that was passed to fopen() and that this object is expected to retrieve. You can use parse_url() to break it apart.

mode is the mode used to open the file, as detailed for fopen(). You are responsible for checking that mode is valid for the path requested.

options holds additional flags set by the streams API. It can hold one or more of the following values OR'd together.

Flag Description
STREAM_USE_PATH If path is relative, search for the resource using the include_path.
STREAM_REPORT_ERRORS If this flag is set, you are responsible for raising errors using trigger_error() during opening of the stream. If this flag is not set, you should not raise any errors.

If the path is opened successfully, and STREAM_USE_PATH is set in options, you should set opened_path to the full path of the file/resource that was actually opened.

If the requested resource was opened successfully, you should return TRUE, otherwise you should return FALSE

This method is called when the stream is closed, using fclose(). You must release any resources that were locked or allocated by the stream.

This method is called in response to fread() and fgets() calls on the stream. You must return up-to count bytes of data from the current read/write position as a string. If there are less than count bytes available, return as many as are available. If no more data is available, return either FALSE or an empty string. You must also update the read/write position of the stream by the number of bytes that were successfully read.

This method is called in response to fwrite() calls on the stream. You should store data into the underlying storage used by your stream. If there is not enough room, try to store as many bytes as possible. You should return the number of bytes that were successfully stored in the stream, or 0 if none could be stored. You must also update the read/write position of the stream by the number of bytes that were successfully written.

This method is called in response to feof() calls on the stream. You should return TRUE if the read/write position is at the end of the stream and if no more data is available to be read, or FALSE otherwise.

This method is called in response to ftell() calls on the stream. You should return the current read/write position of the stream.

This method is called in response to fseek() calls on the stream. You should update the read/write position of the stream according to offset and whence. See fseek() for more information about these parameters. Return TRUE if the position was updated, FALSE otherwise.

This method is called in response to fflush() calls on the stream. If you have cached data in your stream but not yet stored it into the underlying storage, you should do so now. Return TRUE if the cached data was successfully stored (or if there was no data to store), or FALSE if the data could not be stored.

This method is called in response to fstat() calls on the stream and should return an array containing the same values as appropriate for the stream.

This method is called in response to unlink() calls on URL paths associated with the wrapper and should attempt to delete the item specified by path. It should return TRUE on success or FALSE on failure. In order for the appropriate error message to be returned, do not define this method if your wrapper does not support unlinking.

Note:

Userspace wrapper unlink method is not supported prior to PHP 5.0.0.

This method is called in response to rename() calls on URL paths associated with the wrapper and should attempt to rename the item specified by path_from to the specification given by path_to. It should return TRUE on success or FALSE on failure. In order for the appropriate error message to be returned, do not define this method if your wrapper does not support renaming.

Note:

Userspace wrapper rename method is not supported prior to PHP 5.0.0.

This method is called in response to mkdir() calls on URL paths associated with the wrapper and should attempt to create the directory specified by path. It should return TRUE on success or FALSE on failure. In order for the appropriate error message to be returned, do not define this method if your wrapper does not support creating directories. Posible values for options include STREAM_REPORT_ERRORS and STREAM_MKDIR_RECURSIVE.

Note:

Userspace wrapper mkdir method is not supported prior to PHP 5.0.0.

This method is called in response to rmdir() calls on URL paths associated with the wrapper and should attempt to remove the directory specified by path. It should return TRUE on success or FALSE on failure. In order for the appropriate error message to be returned, do not define this method if your wrapper does not support removing directories. Possible values for options include STREAM_REPORT_ERRORS.

Note:

Userspace wrapper rmdir method is not supported prior to PHP 5.0.0.

This method is called immediately when your stream object is created for examining directory contents with opendir(). path specifies the URL that was passed to opendir() and that this object is expected to explore. You can use parse_url() to break it apart.

This method is called in response to stat() calls on the URL paths associated with the wrapper and should return as many elements in common with the system function as possible. Unknown or unavailable values should be set to a rational value (usually 0).

flags holds additional flags set by the streams API. It can hold one or more of the following values OR'd together.

Flag Description
STREAM_URL_STAT_LINK For resources with the ability to link to other resource (such as an HTTP Location: forward, or a filesystem symlink). This flag specified that only information about the link itself should be returned, not the resource pointed to by the link. This flag is set in response to calls to lstat(), is_link(), or filetype().
STREAM_URL_STAT_QUIET If this flag is set, your wrapper should not raise any errors. If this flag is not set, you are responsible for reporting errors using the trigger_error() function during stating of the path.

This method is called in response to readdir() and should return a string representing the next filename in the location opened by dir_opendir().

This method is called in response to rewinddir() and should reset the output generated by dir_readdir(). i.e.: The next call to dir_readdir() should return the first entry in the location returned by dir_opendir().

This method is called in response to closedir(). You should release any resources which were locked or allocated during the opening and use of the directory stream.

The example below implements a var:// protocol handler that allows read/write access to a named global variable using standard filesystem stream functions such as fread(). The var:// protocol implemented below, given the URL "var://foo" will read/write data to/from $GLOBALS["foo"].

Example 2394. A Stream for reading/writing global variables

copy to clipboard
<?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("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);

?>


Code Examples / Notes » stream_wrapper_register

simon
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,",","'"));
?>

anonymouse
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.

fordiman
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);
?>

hayley watson
The current URL standard is RFC 3986 - available at www.ietf.org/rfc/rfc3986.txt

yeiniel
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
 }
}

jhannus
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.

phpnet
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);
?>

none
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

cellog
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!

vmvarela
I have written a new SMB Stream Wrapper for Unix systems using smbclient (SAMBA project).
http://freshmeat.net/smb4php

Change Language


Follow Navioo On Twitter
stream_bucket_append
stream_bucket_make_writeable
stream_bucket_new
stream_bucket_prepend
stream_context_create
stream_context_get_default
stream_context_get_options
stream_context_set_option
stream_context_set_params
stream_copy_to_stream
stream_encoding
stream_filter_append
stream_filter_prepend
stream_filter_register
stream_filter_remove
stream_get_contents
stream_get_filters
stream_get_line
stream_get_meta_data
stream_get_transports
stream_get_wrappers
stream_register_wrapper
stream_resolve_include_path
stream_select
stream_set_blocking
stream_set_timeout
stream_set_write_buffer
stream_socket_accept
stream_socket_client
stream_socket_enable_crypto
stream_socket_get_name
stream_socket_pair
stream_socket_recvfrom
stream_socket_sendto
stream_socket_server
stream_socket_shutdown
stream_wrapper_register
stream_wrapper_restore
stream_wrapper_unregister
Terms of Service Privacy Policy Sitemap

©2024 -EPSILONSYS SOFTWARE inc

Other EPSILONSYS SOFTWARE Web Sites : Programming Resources | News Headline | Free local classifieds

eXTReMe Tracker