From 809d19a9621f23c41f362c1c06c3b31fe1e25507 Mon Sep 17 00:00:00 2001 From: Sara Golemon Date: Mon, 19 May 2003 17:30:43 +0000 Subject: [PATCH] Documentation shuffle per rename of: stream_register_wrapper() and stream_register_filter() to stream_wrapper_register() and stream_filter_register(). git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@127778 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../stream/functions/stream-filter-append.xml | 6 +- .../functions/stream-filter-prepend.xml | 6 +- ...-filter.xml => stream-filter-register.xml} | 21 +- .../stream/functions/stream-get-filters.xml | 4 +- .../stream/functions/stream-get-wrappers.xml | 4 +- .../functions/stream-register-wrapper.xml | 296 +--------------- .../functions/stream-wrapper-register.xml | 319 ++++++++++++++++++ reference/stream/reference.xml | 10 +- 8 files changed, 353 insertions(+), 313 deletions(-) rename reference/stream/functions/{stream-register-filter.xml => stream-filter-register.xml} (91%) create mode 100644 reference/stream/functions/stream-wrapper-register.xml diff --git a/reference/stream/functions/stream-filter-append.xml b/reference/stream/functions/stream-filter-append.xml index 7e9e3201b5..bdb4a63093 100644 --- a/reference/stream/functions/stream-filter-append.xml +++ b/reference/stream/functions/stream-filter-append.xml @@ -1,5 +1,5 @@ - + stream_filter_append @@ -80,13 +80,13 @@ Guvf vf n grfg When using custom (user) filters - stream_register_filter must be called first + stream_filter_register must be called first in order to register the desired user filter to filtername. See also - stream_register_filter, and + stream_filter_register, and stream_filter_prepend diff --git a/reference/stream/functions/stream-filter-prepend.xml b/reference/stream/functions/stream-filter-prepend.xml index 705a4e9ea7..8ae13e1a6e 100644 --- a/reference/stream/functions/stream-filter-prepend.xml +++ b/reference/stream/functions/stream-filter-prepend.xml @@ -1,5 +1,5 @@ - + stream_filter_prepend @@ -41,13 +41,13 @@ When using custom (user) filters - stream_register_filter must be called first + stream_filter_register must be called first in order to register the desired user filter to filtername. See also - stream_register_filter, and + stream_filter_register, and stream_filter_append diff --git a/reference/stream/functions/stream-register-filter.xml b/reference/stream/functions/stream-filter-register.xml similarity index 91% rename from reference/stream/functions/stream-register-filter.xml rename to reference/stream/functions/stream-filter-register.xml index 7afb7d4eb8..8cf7169507 100644 --- a/reference/stream/functions/stream-register-filter.xml +++ b/reference/stream/functions/stream-filter-register.xml @@ -1,19 +1,22 @@ - - + + - stream_register_filter - Register a stream filter implemented as a PHP class derived from php_user_filter + stream_filter_register + + Register a stream filter implemented as a PHP class + derived from php_user_filter + Description - boolstream_register_filter + boolstream_filter_register stringfiltername stringclassname - stream_register_filter allows you to implement + stream_filter_register allows you to implement your own filter on any registered stream used with all the other filesystem functions (such as fopen, fread etc.). @@ -29,7 +32,7 @@ behaviour. - stream_register_filter will return &false; if the + stream_filter_register will return &false; if the filtername is already defined. @@ -109,7 +112,7 @@ class strtoupper_filter extends php_user_filter { } /* Register our filter with PHP */ -stream_register_filter("strtoupper", "strtoupper_filter") +stream_filter_register("strtoupper", "strtoupper_filter") or die("Failed to register filter"); $fp = fopen("foo-bar.txt", "w"); @@ -142,7 +145,7 @@ EASY AS 123 See Also: - stream_register_wrapper, + stream_wrapper_register, stream_filter_prepend, and stream_filter_append diff --git a/reference/stream/functions/stream-get-filters.xml b/reference/stream/functions/stream-get-filters.xml index 2447135da6..59832d7a1c 100644 --- a/reference/stream/functions/stream-get-filters.xml +++ b/reference/stream/functions/stream-get-filters.xml @@ -1,5 +1,5 @@ - + stream_get_filters @@ -43,7 +43,7 @@ Array ( See also - stream_register_filter, and + stream_filter_register, and stream_get_wrappers diff --git a/reference/stream/functions/stream-get-wrappers.xml b/reference/stream/functions/stream-get-wrappers.xml index 2285e6bbd1..fea4eb2aa9 100644 --- a/reference/stream/functions/stream-get-wrappers.xml +++ b/reference/stream/functions/stream-get-wrappers.xml @@ -1,5 +1,5 @@ - + stream_get_wrappers @@ -17,7 +17,7 @@ See also - stream_register_wrapper + stream_wrapper_register diff --git a/reference/stream/functions/stream-register-wrapper.xml b/reference/stream/functions/stream-register-wrapper.xml index f5e17e128b..49dc76e4e5 100644 --- a/reference/stream/functions/stream-register-wrapper.xml +++ b/reference/stream/functions/stream-register-wrapper.xml @@ -1,303 +1,21 @@ - - - + + stream_register_wrapper - Register a URL wrapper implemented as a PHP class + Alias of stream_wrapper_register Description - - boolstream_register_wrapper - stringprotocol - stringclassname - - stream_register_wrapper allows you to implement - your own protocol handlers and streams for use with all the other - filesystem functions (such as fopen, - fread etc.). + This function is an alias of stream_wrapper_register. + This function is included for compatability with PHP 4.3.0 + and PHP 4.3.1 only. stream_wrapper_register + should be used instead. - - 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. - - - stream_register_wrapper will return &false; if the - protocol already has a handler. - - - - boolstream_open - stringpath - stringmode - intoptions - stringopened_path - - - 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; - - - - voidstream_close - void - - - This method is called when the stream is closed, using - fclose. You must release any resources - that were locked or allocated by the stream. - - - - stringstream_read - intcount - - - 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. - - - - intstream_write - stringdata - - - 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. - - - - boolstream_eof - void - - - 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. - - - - intstream_tell - void - - - This method is called in response to ftell - calls on the stream. You should return the current read/write - position of the stream. - - - - boolstream_seek - intoffset - intwhence - - - 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. - - - - boolstream_flush - void - - - 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. - - - - 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"]. - - - A Stream for reading/writing global variables - -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); - -]]> - - - - - + + + stream_wrapper_register + Register a URL wrapper implemented as a PHP class + + + Description + + boolstream_wrapper_register + stringprotocol + stringclassname + + + 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. + + + stream_wrapper_register will return &false; if the + protocol already has a handler. + + + + boolstream_open + stringpath + stringmode + intoptions + stringopened_path + + + 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; + + + + voidstream_close + void + + + This method is called when the stream is closed, using + fclose. You must release any resources + that were locked or allocated by the stream. + + + + stringstream_read + intcount + + + 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. + + + + intstream_write + stringdata + + + 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. + + + + boolstream_eof + void + + + 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. + + + + intstream_tell + void + + + This method is called in response to ftell + calls on the stream. You should return the current read/write + position of the stream. + + + + boolstream_seek + intoffset + intwhence + + + 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. + + + + boolstream_flush + void + + + 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. + + + + 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"]. + + + A Stream for reading/writing global variables + +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); + +]]> + + + + + + + + + diff --git a/reference/stream/reference.xml b/reference/stream/reference.xml index e7fbace7ce..6ebd637215 100644 --- a/reference/stream/reference.xml +++ b/reference/stream/reference.xml @@ -1,5 +1,5 @@ - + Stream functions Streams @@ -25,7 +25,7 @@ request for a file on a remote server. There are many wrappers built into PHP by default (See ), and additional, custom wrappers may be added either within a - PHP script using stream_register_wrapper, + PHP script using stream_wrapper_register, or directly from an extension using the API Reference in . Because any variety of wrapper may be added to PHP, 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 PHP script using - stream_register_filter or in an extension using the + stream_filter_register or in an extension using the API Reference in . To access the list of currently registered filters, use stream_get_filters. @@ -131,13 +131,13 @@
Stream Classes - User designed wrappers can be registered via stream_register_wrapper, + User designed wrappers can be registered via stream_wrapper_register, using the class definition shown on that manual page. class php_user_filter is predefined and is an abstract baseclass for use with user defined filters. See the manual page for - stream_register_filter for details on implementing + stream_filter_register for details on implementing user defined filters.