<HTML ><HEAD ><TITLE >stream_register_wrapper</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK REL="HOME" TITLE="PHP Manual" HREF="index.html"><LINK REL="UP" TITLE="Stream functions" HREF="ref.stream.html"><LINK REL="PREVIOUS" TITLE="stream_register_filter" HREF="function.stream-register-filter.html"><LINK REL="NEXT" TITLE="stream_select" HREF="function.stream-select.html"><META HTTP-EQUIV="Content-type" CONTENT="text/html; charset=ISO-8859-1"></HEAD ><BODY CLASS="refentry" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >PHP Manual</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="function.stream-register-filter.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="function.stream-select.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="function.stream-register-wrapper" ></A >stream_register_wrapper</H1 ><DIV CLASS="refnamediv" ><A NAME="AEN88652" ></A ><P > (PHP 4 >= 4.3.0)</P >stream_register_wrapper -- Register a URL wrapper implemented as a PHP class</DIV ><DIV CLASS="refsect1" ><A NAME="AEN88655" ></A ><H2 >Description</H2 >boolean <B CLASS="methodname" >stream_register_wrapper</B > ( string protocol, string classname)<BR ></BR ><P > <B CLASS="function" >stream_register_wrapper()</B > allows you to implement your own protocol handlers and streams for use with all the other filesystem functions (such as <A HREF="function.fopen.html" ><B CLASS="function" >fopen()</B ></A >, <A HREF="function.fread.html" ><B CLASS="function" >fread()</B ></A > etc.). </P ><P > 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 <TT CLASS="parameter" ><I >classname</I ></TT > and then call methods on that instance. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour. </P ><P > <B CLASS="function" >stream_register_wrapper()</B > will return <TT CLASS="constant" ><B >FALSE</B ></TT > if the <TT CLASS="parameter" ><I >protocol</I ></TT > already has a handler. </P >boolean <B CLASS="methodname" >stream_open</B > ( string path, string mode, int options, string opened_path)<BR ></BR ><P > This method is called immediately after your stream object is created. <TT CLASS="parameter" ><I >path</I ></TT > specifies the URL that was passed to <A HREF="function.fopen.html" ><B CLASS="function" >fopen()</B ></A > and that this object is expected to retrieve. You can use <A HREF="function.parse-url.html" ><B CLASS="function" >parse_url()</B ></A > to break it apart. </P ><P > <TT CLASS="parameter" ><I >mode</I ></TT > is the mode used to open the file, as detailed for <A HREF="function.fopen.html" ><B CLASS="function" >fopen()</B ></A >. You are responsible for checking that <TT CLASS="parameter" ><I >mode</I ></TT > is valid for the <TT CLASS="parameter" ><I >path</I ></TT > requested. </P ><P > <TT CLASS="parameter" ><I >options</I ></TT > holds additional flags set by the streams API. It can hold one or more of the following values OR'd together. <DIV CLASS="informaltable" ><A NAME="AEN88702" ></A ><P ></P ><TABLE BORDER="1" CLASS="CALSTABLE" ><THEAD ><TR ><TH ALIGN="LEFT" VALIGN="MIDDLE" >Flag</TH ><TH ALIGN="LEFT" VALIGN="MIDDLE" >Description</TH ></TR ></THEAD ><TBODY ><TR ><TD ALIGN="LEFT" VALIGN="MIDDLE" >STREAM_USE_PATH</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >If <TT CLASS="parameter" ><I >path</I ></TT > is relative, search for the resource using the include_path. </TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="MIDDLE" >STREAM_REPORT_ERRORS</TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" >If this flag is set, you are responsible for raising errors using <A HREF="function.trigger-error.html" ><B CLASS="function" >trigger_error()</B ></A > during opening of the stream. If this flag is not set, you should not raise any errors. </TD ></TR ></TBODY ></TABLE ><P ></P ></DIV > </P ><P > If the <TT CLASS="parameter" ><I >path</I ></TT > is opened successfully, and STREAM_USE_PATH is set in <TT CLASS="parameter" ><I >options</I ></TT >, you should set <TT CLASS="parameter" ><I >opened_path</I ></TT > to the full path of the file/resource that was actually opened. </P ><P > If the requested resource was opened successfully, you should return <TT CLASS="constant" ><B >TRUE</B ></TT >, otherwise you should return <TT CLASS="constant" ><B >FALSE</B ></TT > </P >void <B CLASS="methodname" >stream_close</B > ( void )<BR ></BR ><P > This method is called when the stream is closed, using <A HREF="function.fclose.html" ><B CLASS="function" >fclose()</B ></A >. You must release any resources that were locked or allocated by the stream. </P >string <B CLASS="methodname" >stream_read</B > ( int count)<BR ></BR ><P > This method is called in response to <A HREF="function.fread.html" ><B CLASS="function" >fread()</B ></A > and <A HREF="function.fgets.html" ><B CLASS="function" >fgets()</B ></A > calls on the stream. You must return up-to <TT CLASS="parameter" ><I >count</I ></TT > bytes of data from the current read/write position as a string. If there are less than <TT CLASS="parameter" ><I >count</I ></TT > bytes available, return as many as are available. If no more data is available, return either <TT CLASS="constant" ><B >FALSE</B ></TT > or an empty string. You must also update the read/write position of the stream by the number of bytes that were successfully read. </P >int <B CLASS="methodname" >stream_write</B > ( string data)<BR ></BR ><P > This method is called in response to <A HREF="function.fwrite.html" ><B CLASS="function" >fwrite()</B ></A > calls on the stream. You should store <TT CLASS="parameter" ><I >data</I ></TT > 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. </P >boolean <B CLASS="methodname" >stream_eof</B > ( void )<BR ></BR ><P > This method is called in response to <A HREF="function.feof.html" ><B CLASS="function" >feof()</B ></A > calls on the stream. You should return <TT CLASS="constant" ><B >TRUE</B ></TT > if the read/write position is at the end of the stream and if no more data is available to be read, or <TT CLASS="constant" ><B >FALSE</B ></TT > otherwise. </P >int <B CLASS="methodname" >stream_tell</B > ( void )<BR ></BR ><P > This method is called in response to <A HREF="function.ftell.html" ><B CLASS="function" >ftell()</B ></A > calls on the stream. You should return the current read/write position of the stream. </P >boolean <B CLASS="methodname" >stream_seek</B > ( int offset, int whence)<BR ></BR ><P > This method is called in response to <A HREF="function.fseek.html" ><B CLASS="function" >fseek()</B ></A > calls on the stream. You should update the read/write position of the stream according to <TT CLASS="parameter" ><I >offset</I ></TT > and <TT CLASS="parameter" ><I >whence</I ></TT >. See <A HREF="function.fseek.html" ><B CLASS="function" >fseek()</B ></A > for more information about these parameters. Return <TT CLASS="constant" ><B >TRUE</B ></TT > if the position was updated, <TT CLASS="constant" ><B >FALSE</B ></TT > otherwise. </P >boolean <B CLASS="methodname" >stream_flush</B > ( void )<BR ></BR ><P > This method is called in response to <A HREF="function.fflush.html" ><B CLASS="function" >fflush()</B ></A > 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 <TT CLASS="constant" ><B >TRUE</B ></TT > if the cached data was successfully stored (or if there was no data to store), or <TT CLASS="constant" ><B >FALSE</B ></TT > if the data could not be stored. </P ><P > 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 <A HREF="function.fread.html" ><B CLASS="function" >fread()</B ></A >. The var:// protocol implemented below, given the url "var://foo" will read/write data to/from $GLOBALS["foo"]. <TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN88799" ></A ><P ><B >Example 1. A Stream for reading/writing global variables</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="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_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);</PRE ></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE > </P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="function.stream-register-filter.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="function.stream-select.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >stream_register_filter</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="ref.stream.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >stream_select</TD ></TR ></TABLE ></DIV ></BODY ></HTML >