cvs: phpdoc /en/reference/stream reference.xml /en/reference/stream/functions stream-filter-append.xml stream-filter-prepend.xml
stream-filter-register.xml stream-get-filters.xml stream-get-wrappers.xml stream-register-filter.xml stream-register-wrapper.xml
stream-wrapper-register.xml
| From: | Sara Golemon | Date: | Mon, 19 May 2003 17:30:43 +0000 |
| Subject: | cvs: phpdoc /en/reference/stream reference.xml /en/reference/stream/functions stream-filter-append.xml stream-filter-prepend.xml stream-filter-register.xml stream-get-filters.xml stream-get-wrappers.xml stream-register-filter.xml stream-register-wrapper.xml stream-wrapper-register.xml |
||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969353656@lists.php.net to get a copy of this message | ||
pollita Mon May 19 13:30:43 2003 EDT
Added files:
/phpdoc/en/reference/stream/functions stream-wrapper-register.xml
stream-filter-register.xml
Removed files:
/phpdoc/en/reference/stream/functions stream-register-filter.xml
Modified files:
/phpdoc/en/reference/stream reference.xml
/phpdoc/en/reference/stream/functions stream-filter-append.xml
stream-filter-prepend.xml
stream-get-filters.xml
stream-get-wrappers.xml
stream-register-wrapper.xml
Log:
Documentation shuffle per rename of:
stream_register_wrapper() and stream_register_filter() to
stream_wrapper_register() and stream_filter_register().
Index: phpdoc/en/reference/stream/reference.xml diff -u phpdoc/en/reference/stream/reference.xml:1.15 phpdoc/en/reference/stream/reference.xml:1.16 --- phpdoc/en/reference/stream/reference.xml:1.15 Thu May 8 16:47:13 2003 +++ phpdoc/en/reference/stream/reference.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.15 $ --> +<!-- $Revision: 1.16 $ --> <reference id="ref.stream"> <title>Stream functions</title> <titleabbrev>Streams</titleabbrev> @@ -25,7 +25,7 @@ request for a file on a remote server. There are many wrappers built into <literal>PHP</literal> by default (See <xref linkend="wrappers"/>), and additional, custom wrappers may be added either within a - PHP script using <function>stream_register_wrapper</function>, + PHP script using <function>stream_wrapper_register</function>, or directly from an extension using the API Reference in <xref linkend="streams"/>. Because any variety of wrapper may be added to <literal>PHP</literal>, there is no set limit on what can be done with them. To access the list @@ -64,7 +64,7 @@ operations on data as it is being read from or written to a stream. Any number of filters may be stacked onto a stream. Custom filters can be defined in a <literal>PHP</literal> script using - <function>stream_register_filter</function> or in an extension using the + <function>stream_filter_register</function> or in an extension using the API Reference in <xref linkend="streams"/>. To access the list of currently registered filters, use <function>stream_get_filters</function>. </simpara> @@ -131,13 +131,13 @@ <section id="stream.resources"> <title>Stream Classes</title> <simpara> - User designed wrappers can be registered via <function>stream_register_wrapper</function>, + User designed wrappers can be registered via <function>stream_wrapper_register</function>, using the class definition shown on that manual page. </simpara> <simpara> <literal>class</literal> php_user_filter is predefined and is an abstract baseclass for use with user defined filters. See the manual page for - <function>stream_register_filter</function> for details on implementing + <function>stream_filter_register</function> for details on implementing user defined filters. </simpara> </section> Index: phpdoc/en/reference/stream/functions/stream-filter-append.xml diff -u phpdoc/en/reference/stream/functions/stream-filter-append.xml:1.6 phpdoc/en/reference/stream/functions/stream-filter-append.xml:1.7 --- phpdoc/en/reference/stream/functions/stream-filter-append.xml:1.6 Thu May 15 07:58:27 2003 +++ phpdoc/en/reference/stream/functions/stream-filter-append.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> +<!-- $Revision: 1.7 $ --> <refentry id="function.stream-filter-append"> <refnamediv> <refname>stream_filter_append</refname> @@ -80,13 +80,13 @@ <note> <title>When using custom (user) filters</title> <simpara> - <function>stream_register_filter</function> must be called first + <function>stream_filter_register</function> must be called first in order to register the desired user filter to <parameter>filtername</parameter>. </simpara> </note> <simpara> See also - <function>stream_register_filter</function>, and + <function>stream_filter_register</function>, and <function>stream_filter_prepend</function> </simpara> </refsect1> Index: phpdoc/en/reference/stream/functions/stream-filter-prepend.xml diff -u phpdoc/en/reference/stream/functions/stream-filter-prepend.xml:1.5 phpdoc/en/reference/stream/functions/stream-filter-prepend.xml:1.6 --- phpdoc/en/reference/stream/functions/stream-filter-prepend.xml:1.5 Sat Apr 26 04:46:18 2003 +++ phpdoc/en/reference/stream/functions/stream-filter-prepend.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <refentry id="function.stream-filter-prepend"> <refnamediv> <refname>stream_filter_prepend</refname> @@ -41,13 +41,13 @@ <note> <title>When using custom (user) filters</title> <simpara> - <function>stream_register_filter</function> must be called first + <function>stream_filter_register</function> must be called first in order to register the desired user filter to <parameter>filtername</parameter>. </simpara> </note> <simpara> See also - <function>stream_register_filter</function>, and + <function>stream_filter_register</function>, and <function>stream_filter_append</function> </simpara> </refsect1> Index: phpdoc/en/reference/stream/functions/stream-get-filters.xml diff -u phpdoc/en/reference/stream/functions/stream-get-filters.xml:1.4 phpdoc/en/reference/stream/functions/stream-get-filters.xml:1.5 --- phpdoc/en/reference/stream/functions/stream-get-filters.xml:1.4 Fri Feb 28 18:48:43 2003 +++ phpdoc/en/reference/stream/functions/stream-get-filters.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <refentry id="function.stream-get-filters"> <refnamediv> <refname>stream_get_filters</refname> @@ -43,7 +43,7 @@ </para> <para> See also - <function>stream_register_filter</function>, and + <function>stream_filter_register</function>, and <function>stream_get_wrappers</function> </para> </refsect1> Index: phpdoc/en/reference/stream/functions/stream-get-wrappers.xml diff -u phpdoc/en/reference/stream/functions/stream-get-wrappers.xml:1.2 phpdoc/en/reference/stream/functions/stream-get-wrappers.xml:1.3 --- phpdoc/en/reference/stream/functions/stream-get-wrappers.xml:1.2 Fri Feb 28 18:48:43 2003 +++ phpdoc/en/reference/stream/functions/stream-get-wrappers.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <refentry id="function.stream-get-wrappers"> <refnamediv> <refname>stream_get_wrappers</refname> @@ -17,7 +17,7 @@ </para> <para> See also - <function>stream_register_wrapper</function> + <function>stream_wrapper_register</function> </para> </refsect1> </refentry> Index: phpdoc/en/reference/stream/functions/stream-register-wrapper.xml diff -u phpdoc/en/reference/stream/functions/stream-register-wrapper.xml:1.2 phpdoc/en/reference/stream/functions/stream-register-wrapper.xml:1.3 --- phpdoc/en/reference/stream/functions/stream-register-wrapper.xml:1.2 Fri Feb 28 18:48:43 2003 +++ phpdoc/en/reference/stream/functions/stream-register-wrapper.xml Mon May 19 13:30:43 2003 @@ -1,302 +1,20 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> -<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.141 --> - <refentry id="function.stream-register-wrapper"> +<!-- $Revision: 1.3 $ --> + <refentry id="stream.stream-register-wrapper"> <refnamediv> <refname>stream_register_wrapper</refname> - <refpurpose>Register a URL wrapper implemented as a PHP class</refpurpose> + <refpurpose>Alias of <function>stream_wrapper_register</function></refpurpose> </refnamediv> <refsect1> <title>Description</title> - <methodsynopsis> - <type>bool</type><methodname>stream_register_wrapper</methodname> - <methodparam><type>string</type><parameter>protocol</parameter></methodparam> - <methodparam><type>string</type><parameter>classname</parameter></methodparam> - </methodsynopsis> <para> - <function>stream_register_wrapper</function> allows you to implement - your own protocol handlers and streams for use with all the other - filesystem functions (such as <function>fopen</function>, - <function>fread</function> etc.). + This function is an alias of <function>stream_wrapper_register</function>. + This function is included for compatability with <literal>PHP 4.3.0</literal> + and <literal>PHP 4.3.1</literal> only. <function>stream_wrapper_register</function> + should be used instead. </para> - <para> - 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 <parameter>classname</parameter> and - then call methods on that instance. You must implement the methods - exactly as described below - doing otherwise will lead to undefined - behaviour. - </para> - <para> - <function>stream_register_wrapper</function> will return &false; if the - <parameter>protocol</parameter> already has a handler. - </para> - - <methodsynopsis> - <type>bool</type><methodname>stream_open</methodname> - <methodparam><type>string</type><parameter>path</parameter></methodparam> - <methodparam><type>string</type><parameter>mode</parameter></methodparam> - <methodparam><type>int</type><parameter>options</parameter></methodparam> - <methodparam><type>string</type><parameter>opened_path</parameter></methodparam> - </methodsynopsis> - <para> - This method is called immediately after your stream object is - created. <parameter>path</parameter> specifies the URL that was - passed to <function>fopen</function> and that this object is - expected to retrieve. You can use <function>parse_url</function> - to break it apart. - </para> - <para> - <parameter>mode</parameter> is the mode used to open the file, - as detailed for <function>fopen</function>. You are responsible - for checking that <parameter>mode</parameter> is valid for the - <parameter>path</parameter> requested. - </para> - <para> - <parameter>options</parameter> holds additional flags set - by the streams API. It can hold one or more of the following - values OR'd together. - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>STREAM_USE_PATH</entry> - <entry>If <parameter>path</parameter> is relative, search - for the resource using the include_path. - </entry> - </row> - <row> - <entry>STREAM_REPORT_ERRORS</entry> - <entry>If this flag is set, you are responsible for raising - errors using <function>trigger_error</function> during - opening of the stream. If this flag is not set, you - should not raise any errors. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - <para> - If the <parameter>path</parameter> is opened successfully, - and STREAM_USE_PATH is set in <parameter>options</parameter>, - you should set <parameter>opened_path</parameter> to the full - path of the file/resource that was actually opened. - </para> - <para> - If the requested resource was opened successfully, you should - return &true;, otherwise you should return &false; - </para> - - <methodsynopsis> - <type>void</type><methodname>stream_close</methodname> - <methodparam><type>void</type><parameter></parameter></methodparam> - </methodsynopsis> - <para> - This method is called when the stream is closed, using - <function>fclose</function>. You must release any resources - that were locked or allocated by the stream. - </para> - - <methodsynopsis> - <type>string</type><methodname>stream_read</methodname> - <methodparam><type>int</type><parameter>count</parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>fread</function> - and <function>fgets</function> calls on the stream. You - must return up-to <parameter>count</parameter> bytes of data - from the current read/write position as a string. - If there are less than <parameter>count</parameter> - 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. - </para> - - <methodsynopsis> - <type>int</type><methodname>stream_write</methodname> - <methodparam><type>string</type><parameter>data</parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>fwrite</function> - calls on the stream. You should store <parameter>data</parameter> - 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. - </para> - - <methodsynopsis> - <type>bool</type><methodname>stream_eof</methodname> - <methodparam><type>void</type><parameter></parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>feof</function> - 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. - </para> - - <methodsynopsis> - <type>int</type><methodname>stream_tell</methodname> - <methodparam><type>void</type><parameter></parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>ftell</function> - calls on the stream. You should return the current read/write - position of the stream. - </para> - - <methodsynopsis> - <type>bool</type><methodname>stream_seek</methodname> - <methodparam><type>int</type><parameter>offset</parameter></methodparam> - <methodparam><type>int</type><parameter>whence</parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>fseek</function> - calls on the stream. You should update the read/write position - of the stream according to <parameter>offset</parameter> and - <parameter>whence</parameter>. See <function>fseek</function> - for more information about these parameters. - Return &true; if the position was updated, &false; otherwise. - </para> - - <methodsynopsis> - <type>bool</type><methodname>stream_flush</methodname> - <methodparam><type>void</type><parameter></parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>fflush</function> - 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. - </para> - - <para> - 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 <function>fread</function>. - The var:// protocol implemented below, given the url - "var://foo" will read/write data to/from $GLOBALS["foo"]. - - <example> - <title>A Stream for reading/writing global variables</title> - <programlisting role="php"> -<![CDATA[ -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); - -]]> - </programlisting> - </example> - </para> - </refsect1> </refentry> - <!-- Keep this comment at the end of the file Local variables: Index: phpdoc/en/reference/stream/functions/stream-wrapper-register.xml +++ phpdoc/en/reference/stream/functions/stream-wrapper-register.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <refentry id="function.stream-wrapper-register"> <refnamediv> <refname>stream_wrapper_register</refname> <refpurpose>Register a URL wrapper implemented as a PHP class</refpurpose> </refnamediv> <refsect1> <title>Description</title> <methodsynopsis> <type>bool</type><methodname>stream_wrapper_register</methodname> <methodparam><type>string</type><parameter>protocol</parameter></methodparam> <methodparam><type>string</type><parameter>classname</parameter></methodparam> </methodsynopsis> <para> <function>stream_wrapper_register</function> allows you to implement your own protocol handlers and streams for use with all the other filesystem functions (such as <function>fopen</function>, <function>fread</function> etc.). </para> <para> 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 <parameter>classname</parameter> and then call methods on that instance. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour. </para> <para> <function>stream_wrapper_register</function> will return &false; if the <parameter>protocol</parameter> already has a handler. </para> <methodsynopsis> <type>bool</type><methodname>stream_open</methodname> <methodparam><type>string</type><parameter>path</parameter></methodparam> <methodparam><type>string</type><parameter>mode</parameter></methodparam> <methodparam><type>int</type><parameter>options</parameter></methodparam> <methodparam><type>string</type><parameter>opened_path</parameter></methodparam> </methodsynopsis> <para> This method is called immediately after your stream object is created. <parameter>path</parameter> specifies the URL that was passed to <function>fopen</function> and that this object is expected to retrieve. You can use <function>parse_url</function> to break it apart. </para> <para> <parameter>mode</parameter> is the mode used to open the file, as detailed for <function>fopen</function>. You are responsible for checking that <parameter>mode</parameter> is valid for the <parameter>path</parameter> requested. </para> <para> <parameter>options</parameter> holds additional flags set by the streams API. It can hold one or more of the following values OR'd together. <informaltable> <tgroup cols="2"> <thead> <row> <entry>Flag</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry>STREAM_USE_PATH</entry> <entry>If <parameter>path</parameter> is relative, search for the resource using the include_path. </entry> </row> <row> <entry>STREAM_REPORT_ERRORS</entry> <entry>If this flag is set, you are responsible for raising errors using <function>trigger_error</function> during opening of the stream. If this flag is not set, you should not raise any errors. </entry> </row> </tbody> </tgroup> </informaltable> </para> <para> If the <parameter>path</parameter> is opened successfully, and STREAM_USE_PATH is set in <parameter>options</parameter>, you should set <parameter>opened_path</parameter> to the full path of the file/resource that was actually opened. </para> <para> If the requested resource was opened successfully, you should return &true;, otherwise you should return &false; </para> <methodsynopsis> <type>void</type><methodname>stream_close</methodname> <methodparam><type>void</type><parameter></parameter></methodparam> </methodsynopsis> <para> This method is called when the stream is closed, using <function>fclose</function>. You must release any resources that were locked or allocated by the stream. </para> <methodsynopsis> <type>string</type><methodname>stream_read</methodname> <methodparam><type>int</type><parameter>count</parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>fread</function> and <function>fgets</function> calls on the stream. You must return up-to <parameter>count</parameter> bytes of data from the current read/write position as a string. If there are less than <parameter>count</parameter> 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. </para> <methodsynopsis> <type>int</type><methodname>stream_write</methodname> <methodparam><type>string</type><parameter>data</parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>fwrite</function> calls on the stream. You should store <parameter>data</parameter> 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. </para> <methodsynopsis> <type>bool</type><methodname>stream_eof</methodname> <methodparam><type>void</type><parameter></parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>feof</function> 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. </para> <methodsynopsis> <type>int</type><methodname>stream_tell</methodname> <methodparam><type>void</type><parameter></parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>ftell</function> calls on the stream. You should return the current read/write position of the stream. </para> <methodsynopsis> <type>bool</type><methodname>stream_seek</methodname> <methodparam><type>int</type><parameter>offset</parameter></methodparam> <methodparam><type>int</type><parameter>whence</parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>fseek</function> calls on the stream. You should update the read/write position of the stream according to <parameter>offset</parameter> and <parameter>whence</parameter>. See <function>fseek</function> for more information about these parameters. Return &true; if the position was updated, &false; otherwise. </para> <methodsynopsis> <type>bool</type><methodname>stream_flush</methodname> <methodparam><type>void</type><parameter></parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>fflush</function> 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. </para> <para> 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 <function>fread</function>. The var:// protocol implemented below, given the url "var://foo" will read/write data to/from $GLOBALS["foo"]. <example> <title>A Stream for reading/writing global variables</title> <programlisting role="php"> <![CDATA[ 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); ]]> </programlisting> </example> </para> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> Index: phpdoc/en/reference/stream/functions/stream-filter-register.xml +++ phpdoc/en/reference/stream/functions/stream-filter-register.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <refentry id="function.stream-filter-register"> <refnamediv> <refname>stream_filter_register</refname> <refpurpose> Register a stream filter implemented as a PHP class derived from <literal>php_user_filter</literal> </refpurpose> </refnamediv> <refsect1> <title>Description</title> <methodsynopsis> <type>bool</type><methodname>stream_filter_register</methodname> <methodparam><type>string</type><parameter>filtername</parameter></methodparam> <methodparam><type>string</type><parameter>classname</parameter></methodparam> </methodsynopsis> <para> <function>stream_filter_register</function> allows you to implement your own filter on any registered stream used with all the other filesystem functions (such as <function>fopen</function>, <function>fread</function> etc.). </para> <para> To implement a filter, you need to define a class as an extension of <literal>php_user_filter</literal> with a number of member functions as defined below. When performing read/write operations on the stream to which your filter is attached, PHP will pass the data through your filter (and any other filters attached to that stream) so that the data may be modified as desired. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour. </para> <para> <function>stream_filter_register</function> will return &false; if the <parameter>filtername</parameter> is already defined. </para> <methodsynopsis> <type>int</type><methodname>filter</methodname> <methodparam><type>resource</type><parameter>in</parameter></methodparam> <methodparam><type>resource</type><parameter>out</parameter></methodparam> <methodparam><type>int</type><parameter>&consumed</parameter></methodparam> <methodparam><type>boolean</type><parameter>closing</parameter></methodparam> </methodsynopsis> <para> This method is called whenever data is read from or written to the attached stream (such as with <function>fread</function> or <function>fwrite</function>). <parameter>in</parameter> is a resource pointing to a <literal>bucket brigade</literal> which contains one or more <literal>bucket</literal> objects containing data to be filtered. <parameter>out</parameter> is a resource pointing to a second <literal>bucket brigade</literal> into which your modified buckets should be placed. <parameter>consumed</parameter>, which must <emphasis>always</emphasis> be declared by reference, should be incremented by the length of the data which your filter reads in and alters. In most cases this means you will increment <parameter>consumed</parameter> by $bucket->datalen for each $bucket. If the stream is in the process of closing (and therefore this is the last pass through the filterchain), the <parameter>closing</parameter> parameter will be set to &true; The <methodname>filter</methodname> method must return one of three values upon completion. <constant>PSFS_PASS_ON</constant> indicates success with data available in the <parameter>out</parameter> <literal>bucket brigade</literal>. <constant>PSFS_FEED_ME</constant> indicates that the filter has no data available to return and requires additional data from the stream. <constant>PSFS_ERR_FATAL</constant> indicates that the filter experienced an unrecoverable error and cannot continue. If no value is returned by this method, <constant>PSFS_ERR_FATAL</constant> will be assumed. </para> <methodsynopsis> <type>void</type><methodname>oncreate</methodname> <void/> </methodsynopsis> <para> This method is called during instantiation of the filter class object. If your filter allocates or initializes any other resources (such as a buffer), this is the place to do it. </para> <methodsynopsis> <type>void</type><methodname>onclose</methodname> <void/> </methodsynopsis> <para> This method is called upon filter shutdown (typically, this is also during stream shutdown), and is executed <emphasis>after</emphasis> the <literal>flush</literal> method is called. If any resources were allocated or initialzed during <literal>oncreate</literal> this would be the time to destroy or dispose of them. </para> <para> The example below implements a filter named <literal>strtoupper</literal> on the <literal>foo-bar.txt</literal> stream which will capitalize all letter characters written to/read from that stream. <example> <title>Filter for capitalizing characters on foo-bar.txt stream</title> <programlisting role="php"> <![CDATA[ <?php /* Define our filter class */ class strtoupper_filter extends php_user_filter { function filter($in, $out, &$consumed, $closing) { while ($bucket = stream_bucket_make_writeable($in)) { $bucket->data = strtoupper($bucket->data); $consumed += $bucket->datalen; stream_bucket_append($out, $bucket); } return PSFS_PASS_ON; } } /* Register our filter with PHP */ stream_filter_register("strtoupper", "strtoupper_filter") or die("Failed to register filter"); $fp = fopen("foo-bar.txt", "w"); /* Attach the registered filter to the stream just opened */ stream_filter_append($fp, "strtoupper"); fwrite($fp, "Line1\n"); fwrite($fp, "Word - 2\n"); fwrite($fp, "Easy As 123\n"); fclose($fp); /* Read the contents back out */ readfile("foo-bar.txt"); /* Output * ------ LINE1 WORD - 2 EASY AS 123 */ ?> ]]> </programlisting> </example> </para> <simpara> See Also: <function>stream_wrapper_register</function>, <function>stream_filter_prepend</function>, and <function>stream_filter_append</function> </simpara> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->
Index: phpdoc/en/reference/stream/reference.xml diff -u phpdoc/en/reference/stream/reference.xml:1.15 phpdoc/en/reference/stream/reference.xml:1.16 --- phpdoc/en/reference/stream/reference.xml:1.15 Thu May 8 16:47:13 2003 +++ phpdoc/en/reference/stream/reference.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.15 $ --> +<!-- $Revision: 1.16 $ --> <reference id="ref.stream"> <title>Stream functions</title> <titleabbrev>Streams</titleabbrev> @@ -25,7 +25,7 @@ request for a file on a remote server. There are many wrappers built into <literal>PHP</literal> by default (See <xref linkend="wrappers"/>), and additional, custom wrappers may be added either within a - PHP script using <function>stream_register_wrapper</function>, + PHP script using <function>stream_wrapper_register</function>, or directly from an extension using the API Reference in <xref linkend="streams"/>. Because any variety of wrapper may be added to <literal>PHP</literal>, there is no set limit on what can be done with them. To access the list @@ -64,7 +64,7 @@ operations on data as it is being read from or written to a stream. Any number of filters may be stacked onto a stream. Custom filters can be defined in a <literal>PHP</literal> script using - <function>stream_register_filter</function> or in an extension using the + <function>stream_filter_register</function> or in an extension using the API Reference in <xref linkend="streams"/>. To access the list of currently registered filters, use <function>stream_get_filters</function>. </simpara> @@ -131,13 +131,13 @@ <section id="stream.resources"> <title>Stream Classes</title> <simpara> - User designed wrappers can be registered via <function>stream_register_wrapper</function>, + User designed wrappers can be registered via <function>stream_wrapper_register</function>, using the class definition shown on that manual page. </simpara> <simpara> <literal>class</literal> php_user_filter is predefined and is an abstract baseclass for use with user defined filters. See the manual page for - <function>stream_register_filter</function> for details on implementing + <function>stream_filter_register</function> for details on implementing user defined filters. </simpara> </section> Index: phpdoc/en/reference/stream/functions/stream-filter-append.xml diff -u phpdoc/en/reference/stream/functions/stream-filter-append.xml:1.6 phpdoc/en/reference/stream/functions/stream-filter-append.xml:1.7 --- phpdoc/en/reference/stream/functions/stream-filter-append.xml:1.6 Thu May 15 07:58:27 2003 +++ phpdoc/en/reference/stream/functions/stream-filter-append.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> +<!-- $Revision: 1.7 $ --> <refentry id="function.stream-filter-append"> <refnamediv> <refname>stream_filter_append</refname> @@ -80,13 +80,13 @@ <note> <title>When using custom (user) filters</title> <simpara> - <function>stream_register_filter</function> must be called first + <function>stream_filter_register</function> must be called first in order to register the desired user filter to <parameter>filtername</parameter>. </simpara> </note> <simpara> See also - <function>stream_register_filter</function>, and + <function>stream_filter_register</function>, and <function>stream_filter_prepend</function> </simpara> </refsect1> Index: phpdoc/en/reference/stream/functions/stream-filter-prepend.xml diff -u phpdoc/en/reference/stream/functions/stream-filter-prepend.xml:1.5 phpdoc/en/reference/stream/functions/stream-filter-prepend.xml:1.6 --- phpdoc/en/reference/stream/functions/stream-filter-prepend.xml:1.5 Sat Apr 26 04:46:18 2003 +++ phpdoc/en/reference/stream/functions/stream-filter-prepend.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <refentry id="function.stream-filter-prepend"> <refnamediv> <refname>stream_filter_prepend</refname> @@ -41,13 +41,13 @@ <note> <title>When using custom (user) filters</title> <simpara> - <function>stream_register_filter</function> must be called first + <function>stream_filter_register</function> must be called first in order to register the desired user filter to <parameter>filtername</parameter>. </simpara> </note> <simpara> See also - <function>stream_register_filter</function>, and + <function>stream_filter_register</function>, and <function>stream_filter_append</function> </simpara> </refsect1> Index: phpdoc/en/reference/stream/functions/stream-get-filters.xml diff -u phpdoc/en/reference/stream/functions/stream-get-filters.xml:1.4 phpdoc/en/reference/stream/functions/stream-get-filters.xml:1.5 --- phpdoc/en/reference/stream/functions/stream-get-filters.xml:1.4 Fri Feb 28 18:48:43 2003 +++ phpdoc/en/reference/stream/functions/stream-get-filters.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <refentry id="function.stream-get-filters"> <refnamediv> <refname>stream_get_filters</refname> @@ -43,7 +43,7 @@ </para> <para> See also - <function>stream_register_filter</function>, and + <function>stream_filter_register</function>, and <function>stream_get_wrappers</function> </para> </refsect1> Index: phpdoc/en/reference/stream/functions/stream-get-wrappers.xml diff -u phpdoc/en/reference/stream/functions/stream-get-wrappers.xml:1.2 phpdoc/en/reference/stream/functions/stream-get-wrappers.xml:1.3 --- phpdoc/en/reference/stream/functions/stream-get-wrappers.xml:1.2 Fri Feb 28 18:48:43 2003 +++ phpdoc/en/reference/stream/functions/stream-get-wrappers.xml Mon May 19 13:30:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <refentry id="function.stream-get-wrappers"> <refnamediv> <refname>stream_get_wrappers</refname> @@ -17,7 +17,7 @@ </para> <para> See also - <function>stream_register_wrapper</function> + <function>stream_wrapper_register</function> </para> </refsect1> </refentry> Index: phpdoc/en/reference/stream/functions/stream-register-wrapper.xml diff -u phpdoc/en/reference/stream/functions/stream-register-wrapper.xml:1.2 phpdoc/en/reference/stream/functions/stream-register-wrapper.xml:1.3 --- phpdoc/en/reference/stream/functions/stream-register-wrapper.xml:1.2 Fri Feb 28 18:48:43 2003 +++ phpdoc/en/reference/stream/functions/stream-register-wrapper.xml Mon May 19 13:30:43 2003 @@ -1,302 +1,20 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> -<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.141 --> - <refentry id="function.stream-register-wrapper"> +<!-- $Revision: 1.3 $ --> + <refentry id="stream.stream-register-wrapper"> <refnamediv> <refname>stream_register_wrapper</refname> - <refpurpose>Register a URL wrapper implemented as a PHP class</refpurpose> + <refpurpose>Alias of <function>stream_wrapper_register</function></refpurpose> </refnamediv> <refsect1> <title>Description</title> - <methodsynopsis> - <type>bool</type><methodname>stream_register_wrapper</methodname> - <methodparam><type>string</type><parameter>protocol</parameter></methodparam> - <methodparam><type>string</type><parameter>classname</parameter></methodparam> - </methodsynopsis> <para> - <function>stream_register_wrapper</function> allows you to implement - your own protocol handlers and streams for use with all the other - filesystem functions (such as <function>fopen</function>, - <function>fread</function> etc.). + This function is an alias of <function>stream_wrapper_register</function>. + This function is included for compatability with <literal>PHP 4.3.0</literal> + and <literal>PHP 4.3.1</literal> only. <function>stream_wrapper_register</function> + should be used instead. </para> - <para> - 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 <parameter>classname</parameter> and - then call methods on that instance. You must implement the methods - exactly as described below - doing otherwise will lead to undefined - behaviour. - </para> - <para> - <function>stream_register_wrapper</function> will return &false; if the - <parameter>protocol</parameter> already has a handler. - </para> - - <methodsynopsis> - <type>bool</type><methodname>stream_open</methodname> - <methodparam><type>string</type><parameter>path</parameter></methodparam> - <methodparam><type>string</type><parameter>mode</parameter></methodparam> - <methodparam><type>int</type><parameter>options</parameter></methodparam> - <methodparam><type>string</type><parameter>opened_path</parameter></methodparam> - </methodsynopsis> - <para> - This method is called immediately after your stream object is - created. <parameter>path</parameter> specifies the URL that was - passed to <function>fopen</function> and that this object is - expected to retrieve. You can use <function>parse_url</function> - to break it apart. - </para> - <para> - <parameter>mode</parameter> is the mode used to open the file, - as detailed for <function>fopen</function>. You are responsible - for checking that <parameter>mode</parameter> is valid for the - <parameter>path</parameter> requested. - </para> - <para> - <parameter>options</parameter> holds additional flags set - by the streams API. It can hold one or more of the following - values OR'd together. - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Flag</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>STREAM_USE_PATH</entry> - <entry>If <parameter>path</parameter> is relative, search - for the resource using the include_path. - </entry> - </row> - <row> - <entry>STREAM_REPORT_ERRORS</entry> - <entry>If this flag is set, you are responsible for raising - errors using <function>trigger_error</function> during - opening of the stream. If this flag is not set, you - should not raise any errors. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - <para> - If the <parameter>path</parameter> is opened successfully, - and STREAM_USE_PATH is set in <parameter>options</parameter>, - you should set <parameter>opened_path</parameter> to the full - path of the file/resource that was actually opened. - </para> - <para> - If the requested resource was opened successfully, you should - return &true;, otherwise you should return &false; - </para> - - <methodsynopsis> - <type>void</type><methodname>stream_close</methodname> - <methodparam><type>void</type><parameter></parameter></methodparam> - </methodsynopsis> - <para> - This method is called when the stream is closed, using - <function>fclose</function>. You must release any resources - that were locked or allocated by the stream. - </para> - - <methodsynopsis> - <type>string</type><methodname>stream_read</methodname> - <methodparam><type>int</type><parameter>count</parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>fread</function> - and <function>fgets</function> calls on the stream. You - must return up-to <parameter>count</parameter> bytes of data - from the current read/write position as a string. - If there are less than <parameter>count</parameter> - 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. - </para> - - <methodsynopsis> - <type>int</type><methodname>stream_write</methodname> - <methodparam><type>string</type><parameter>data</parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>fwrite</function> - calls on the stream. You should store <parameter>data</parameter> - 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. - </para> - - <methodsynopsis> - <type>bool</type><methodname>stream_eof</methodname> - <methodparam><type>void</type><parameter></parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>feof</function> - 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. - </para> - - <methodsynopsis> - <type>int</type><methodname>stream_tell</methodname> - <methodparam><type>void</type><parameter></parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>ftell</function> - calls on the stream. You should return the current read/write - position of the stream. - </para> - - <methodsynopsis> - <type>bool</type><methodname>stream_seek</methodname> - <methodparam><type>int</type><parameter>offset</parameter></methodparam> - <methodparam><type>int</type><parameter>whence</parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>fseek</function> - calls on the stream. You should update the read/write position - of the stream according to <parameter>offset</parameter> and - <parameter>whence</parameter>. See <function>fseek</function> - for more information about these parameters. - Return &true; if the position was updated, &false; otherwise. - </para> - - <methodsynopsis> - <type>bool</type><methodname>stream_flush</methodname> - <methodparam><type>void</type><parameter></parameter></methodparam> - </methodsynopsis> - <para> - This method is called in response to <function>fflush</function> - 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. - </para> - - <para> - 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 <function>fread</function>. - The var:// protocol implemented below, given the url - "var://foo" will read/write data to/from $GLOBALS["foo"]. - - <example> - <title>A Stream for reading/writing global variables</title> - <programlisting role="php"> -<![CDATA[ -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); - -]]> - </programlisting> - </example> - </para> - </refsect1> </refentry> - <!-- Keep this comment at the end of the file Local variables: Index: phpdoc/en/reference/stream/functions/stream-wrapper-register.xml +++ phpdoc/en/reference/stream/functions/stream-wrapper-register.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <refentry id="function.stream-wrapper-register"> <refnamediv> <refname>stream_wrapper_register</refname> <refpurpose>Register a URL wrapper implemented as a PHP class</refpurpose> </refnamediv> <refsect1> <title>Description</title> <methodsynopsis> <type>bool</type><methodname>stream_wrapper_register</methodname> <methodparam><type>string</type><parameter>protocol</parameter></methodparam> <methodparam><type>string</type><parameter>classname</parameter></methodparam> </methodsynopsis> <para> <function>stream_wrapper_register</function> allows you to implement your own protocol handlers and streams for use with all the other filesystem functions (such as <function>fopen</function>, <function>fread</function> etc.). </para> <para> 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 <parameter>classname</parameter> and then call methods on that instance. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour. </para> <para> <function>stream_wrapper_register</function> will return &false; if the <parameter>protocol</parameter> already has a handler. </para> <methodsynopsis> <type>bool</type><methodname>stream_open</methodname> <methodparam><type>string</type><parameter>path</parameter></methodparam> <methodparam><type>string</type><parameter>mode</parameter></methodparam> <methodparam><type>int</type><parameter>options</parameter></methodparam> <methodparam><type>string</type><parameter>opened_path</parameter></methodparam> </methodsynopsis> <para> This method is called immediately after your stream object is created. <parameter>path</parameter> specifies the URL that was passed to <function>fopen</function> and that this object is expected to retrieve. You can use <function>parse_url</function> to break it apart. </para> <para> <parameter>mode</parameter> is the mode used to open the file, as detailed for <function>fopen</function>. You are responsible for checking that <parameter>mode</parameter> is valid for the <parameter>path</parameter> requested. </para> <para> <parameter>options</parameter> holds additional flags set by the streams API. It can hold one or more of the following values OR'd together. <informaltable> <tgroup cols="2"> <thead> <row> <entry>Flag</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry>STREAM_USE_PATH</entry> <entry>If <parameter>path</parameter> is relative, search for the resource using the include_path. </entry> </row> <row> <entry>STREAM_REPORT_ERRORS</entry> <entry>If this flag is set, you are responsible for raising errors using <function>trigger_error</function> during opening of the stream. If this flag is not set, you should not raise any errors. </entry> </row> </tbody> </tgroup> </informaltable> </para> <para> If the <parameter>path</parameter> is opened successfully, and STREAM_USE_PATH is set in <parameter>options</parameter>, you should set <parameter>opened_path</parameter> to the full path of the file/resource that was actually opened. </para> <para> If the requested resource was opened successfully, you should return &true;, otherwise you should return &false; </para> <methodsynopsis> <type>void</type><methodname>stream_close</methodname> <methodparam><type>void</type><parameter></parameter></methodparam> </methodsynopsis> <para> This method is called when the stream is closed, using <function>fclose</function>. You must release any resources that were locked or allocated by the stream. </para> <methodsynopsis> <type>string</type><methodname>stream_read</methodname> <methodparam><type>int</type><parameter>count</parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>fread</function> and <function>fgets</function> calls on the stream. You must return up-to <parameter>count</parameter> bytes of data from the current read/write position as a string. If there are less than <parameter>count</parameter> 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. </para> <methodsynopsis> <type>int</type><methodname>stream_write</methodname> <methodparam><type>string</type><parameter>data</parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>fwrite</function> calls on the stream. You should store <parameter>data</parameter> 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. </para> <methodsynopsis> <type>bool</type><methodname>stream_eof</methodname> <methodparam><type>void</type><parameter></parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>feof</function> 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. </para> <methodsynopsis> <type>int</type><methodname>stream_tell</methodname> <methodparam><type>void</type><parameter></parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>ftell</function> calls on the stream. You should return the current read/write position of the stream. </para> <methodsynopsis> <type>bool</type><methodname>stream_seek</methodname> <methodparam><type>int</type><parameter>offset</parameter></methodparam> <methodparam><type>int</type><parameter>whence</parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>fseek</function> calls on the stream. You should update the read/write position of the stream according to <parameter>offset</parameter> and <parameter>whence</parameter>. See <function>fseek</function> for more information about these parameters. Return &true; if the position was updated, &false; otherwise. </para> <methodsynopsis> <type>bool</type><methodname>stream_flush</methodname> <methodparam><type>void</type><parameter></parameter></methodparam> </methodsynopsis> <para> This method is called in response to <function>fflush</function> 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. </para> <para> 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 <function>fread</function>. The var:// protocol implemented below, given the url "var://foo" will read/write data to/from $GLOBALS["foo"]. <example> <title>A Stream for reading/writing global variables</title> <programlisting role="php"> <![CDATA[ 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); ]]> </programlisting> </example> </para> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> Index: phpdoc/en/reference/stream/functions/stream-filter-register.xml +++ phpdoc/en/reference/stream/functions/stream-filter-register.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <refentry id="function.stream-filter-register"> <refnamediv> <refname>stream_filter_register</refname> <refpurpose> Register a stream filter implemented as a PHP class derived from <literal>php_user_filter</literal> </refpurpose> </refnamediv> <refsect1> <title>Description</title> <methodsynopsis> <type>bool</type><methodname>stream_filter_register</methodname> <methodparam><type>string</type><parameter>filtername</parameter></methodparam> <methodparam><type>string</type><parameter>classname</parameter></methodparam> </methodsynopsis> <para> <function>stream_filter_register</function> allows you to implement your own filter on any registered stream used with all the other filesystem functions (such as <function>fopen</function>, <function>fread</function> etc.). </para> <para> To implement a filter, you need to define a class as an extension of <literal>php_user_filter</literal> with a number of member functions as defined below. When performing read/write operations on the stream to which your filter is attached, PHP will pass the data through your filter (and any other filters attached to that stream) so that the data may be modified as desired. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour. </para> <para> <function>stream_filter_register</function> will return &false; if the <parameter>filtername</parameter> is already defined. </para> <methodsynopsis> <type>int</type><methodname>filter</methodname> <methodparam><type>resource</type><parameter>in</parameter></methodparam> <methodparam><type>resource</type><parameter>out</parameter></methodparam> <methodparam><type>int</type><parameter>&consumed</parameter></methodparam> <methodparam><type>boolean</type><parameter>closing</parameter></methodparam> </methodsynopsis> <para> This method is called whenever data is read from or written to the attached stream (such as with <function>fread</function> or <function>fwrite</function>). <parameter>in</parameter> is a resource pointing to a <literal>bucket brigade</literal> which contains one or more <literal>bucket</literal> objects containing data to be filtered. <parameter>out</parameter> is a resource pointing to a second <literal>bucket brigade</literal> into which your modified buckets should be placed. <parameter>consumed</parameter>, which must <emphasis>always</emphasis> be declared by reference, should be incremented by the length of the data which your filter reads in and alters. In most cases this means you will increment <parameter>consumed</parameter> by $bucket->datalen for each $bucket. If the stream is in the process of closing (and therefore this is the last pass through the filterchain), the <parameter>closing</parameter> parameter will be set to &true; The <methodname>filter</methodname> method must return one of three values upon completion. <constant>PSFS_PASS_ON</constant> indicates success with data available in the <parameter>out</parameter> <literal>bucket brigade</literal>. <constant>PSFS_FEED_ME</constant> indicates that the filter has no data available to return and requires additional data from the stream. <constant>PSFS_ERR_FATAL</constant> indicates that the filter experienced an unrecoverable error and cannot continue. If no value is returned by this method, <constant>PSFS_ERR_FATAL</constant> will be assumed. </para> <methodsynopsis> <type>void</type><methodname>oncreate</methodname> <void/> </methodsynopsis> <para> This method is called during instantiation of the filter class object. If your filter allocates or initializes any other resources (such as a buffer), this is the place to do it. </para> <methodsynopsis> <type>void</type><methodname>onclose</methodname> <void/> </methodsynopsis> <para> This method is called upon filter shutdown (typically, this is also during stream shutdown), and is executed <emphasis>after</emphasis> the <literal>flush</literal> method is called. If any resources were allocated or initialzed during <literal>oncreate</literal> this would be the time to destroy or dispose of them. </para> <para> The example below implements a filter named <literal>strtoupper</literal> on the <literal>foo-bar.txt</literal> stream which will capitalize all letter characters written to/read from that stream. <example> <title>Filter for capitalizing characters on foo-bar.txt stream</title> <programlisting role="php"> <![CDATA[ <?php /* Define our filter class */ class strtoupper_filter extends php_user_filter { function filter($in, $out, &$consumed, $closing) { while ($bucket = stream_bucket_make_writeable($in)) { $bucket->data = strtoupper($bucket->data); $consumed += $bucket->datalen; stream_bucket_append($out, $bucket); } return PSFS_PASS_ON; } } /* Register our filter with PHP */ stream_filter_register("strtoupper", "strtoupper_filter") or die("Failed to register filter"); $fp = fopen("foo-bar.txt", "w"); /* Attach the registered filter to the stream just opened */ stream_filter_append($fp, "strtoupper"); fwrite($fp, "Line1\n"); fwrite($fp, "Word - 2\n"); fwrite($fp, "Easy As 123\n"); fclose($fp); /* Read the contents back out */ readfile("foo-bar.txt"); /* Output * ------ LINE1 WORD - 2 EASY AS 123 */ ?> ]]> </programlisting> </example> </para> <simpara> See Also: <function>stream_wrapper_register</function>, <function>stream_filter_prepend</function>, and <function>stream_filter_append</function> </simpara> </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->