From 1477e2e71fdbfc1a38dbfc4a7e2386bd859887f3 Mon Sep 17 00:00:00 2001 From: Hannes Magnusson Date: Wed, 25 Mar 2009 18:03:59 +0000 Subject: [PATCH] - Refactor more information from stream_wrapper_register to the method prototypes - Refactor the example from stream_wrapper_register to the examples chapter - Refactored the changelog from stream_wrapper_register to the class prototype - Added an example for stream_wrapper_register - Added a seealso for stream_wrapper_register - Added versioninfo git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@277771 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/stream/examples.xml | 130 ++++++++- .../functions/stream-wrapper-register.xml | 253 +++--------------- reference/stream/streamwrapper.xml | 49 +++- .../stream/streamwrapper/stream-read.xml | 31 ++- .../stream/streamwrapper/stream-seek.xml | 32 ++- .../streamwrapper/stream-set-option.xml | 46 +++- .../stream/streamwrapper/stream-tell.xml | 15 +- .../stream/streamwrapper/stream-write.xml | 30 ++- reference/stream/versions.xml | 23 +- 9 files changed, 337 insertions(+), 272 deletions(-) diff --git a/reference/stream/examples.xml b/reference/stream/examples.xml index 3d7340b79a..d985d08b2c 100644 --- a/reference/stream/examples.xml +++ b/reference/stream/examples.xml @@ -1,5 +1,5 @@ - + &reftitle.examples; @@ -92,6 +92,134 @@ fclose($fp); + +
+ Example class registered as stream wrapper + + 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); + +?> +]]> + + &example.outputs; + + + + + +
+ stream_wrapper_register @@ -35,98 +35,7 @@ classname - 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. - - - - 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. - - - - intstream_tell - - - - 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_set_option - intoption - intarg1 - intarg2 - - - This method is called to set options on the stream. Possible values - for option are: - - STREAM_OPTION_BLOCKING: The method is called - in response to stream_set_blocking. - arg1 is the requested blocking mode. - STREAM_OPTION_READ_TIMEOUT: The method is - called in response to stream_set_timeout. - arg1 is the timeout in seconds, and - arg2 is the timeout in microseconds. - STREAM_OPTION_WRITE_BUFFER: The method is - called in response to stream_set_write_buffer. - arg1 is the buffer mode - (STREAM_BUFFER_NONE or - STREAM_BUFFER_FULL) and arg2 - is the requested buffer size. - - - - stream_set_option should return &false; on failure or - if the option is not implemented, &true; otherwise. + The classname which implements the protocol. @@ -145,136 +54,19 @@ - - &reftitle.changelog; - - - - - - &Version; - &Description; - - - - - 5.3.0 - - Added the following userspace wrappers: stream_set_option, stream_cast. - - - - 5.0.0 - - Added the following userspace wrappers: rmdir, mkdir, rename, unlink. - - - - 5.0.0 - - Added the context property. - - - - - - - - &reftitle.examples; - A Stream for reading/writing global variables - - 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"]. - + How to register a stream wrapper 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; - } - } +$existed = in_array("var", stream_get_wrappers()); +if ($existed) { + stream_wrapper_unregister("var"); } - -stream_wrapper_register("var", "VariableStream") - or die("Failed to register protocol"); - +stream_wrapper_register("var", "VariableStream"); $myvar = ""; $fp = fopen("var://myvar", "r+"); @@ -290,14 +82,43 @@ while (!feof($fp)) { fclose($fp); var_dump($myvar); +if ($existed) { + stream_wrapper_restore("var"); +} + ?> ]]> + &example.outputs; + + + - + + &reftitle.seealso; + + + The prototype class + + stream_wrapper_unregister + stream_wrapper_restore + stream_get_wrappers + + + + + diff --git a/reference/stream/streamwrapper.xml b/reference/stream/streamwrapper.xml index 4ed4136b41..16a9df41ad 100644 --- a/reference/stream/streamwrapper.xml +++ b/reference/stream/streamwrapper.xml @@ -1,5 +1,5 @@ - + @@ -22,6 +22,16 @@ a class defining its own protocol should be. + + + Implementing the methods in otherways then described here can lead to + undefed behaviour. + + + + An instance of this class is initialized as soon as a stream function + tries to access the protocol it is associated with. + @@ -87,6 +97,43 @@ +
+ &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.0.0 + + Added the context property. + + + + + + +
+ + + &reftitle.seealso; + + + + stream_wrapper_register + stream_wrapper_unregister + stream_wrapper_restore + + + + + diff --git a/reference/stream/streamwrapper/stream-read.xml b/reference/stream/streamwrapper/stream-read.xml index ff5f241371..4561049f95 100644 --- a/reference/stream/streamwrapper/stream-read.xml +++ b/reference/stream/streamwrapper/stream-read.xml @@ -1,23 +1,28 @@ - + streamWrapper::stream_read - The stream_read purpose + Read from stream &reftitle.description; - public voidstreamWrapper::stream_read - stringcount + public stringstreamWrapper::stream_read + intcount - The method description goes here. + This method is called in response to fread + and fgets. - - &warn.undocumented.func; + + + Remember to update the read/write position of the stream (by the number of + bytes that were successfully read). + + @@ -29,7 +34,7 @@ count - Description... + How many bytes of data from the current position should be returned. @@ -40,10 +45,14 @@ &reftitle.returnvalues; - Description... + 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. + &reftitle.seealso; - Classname::Method + fread + fgets diff --git a/reference/stream/streamwrapper/stream-seek.xml b/reference/stream/streamwrapper/stream-seek.xml index 391eb50796..7f80f7f2a6 100644 --- a/reference/stream/streamwrapper/stream-seek.xml +++ b/reference/stream/streamwrapper/stream-seek.xml @@ -1,5 +1,5 @@ - + @@ -10,16 +10,17 @@ &reftitle.description; - public voidstreamWrapper::stream_seek - stringoffset - stringwhence + public boolstreamWrapper::stream_seek + intoffset + intwhence SEEK_SET - The method description goes here. + This method is called in response to fseek. + + + The read/write position of the stream should be updated according to the + offset and whence. - - &warn.undocumented.func; - @@ -30,7 +31,7 @@ offset - Description... + The stream offset to seek to. @@ -38,7 +39,12 @@ whence - Description... + Possible values: + + SEEK_SET - Set position equal to offset bytes. + SEEK_CUR - Set position to current location plus offset. + SEEK_END - Set position to end-of-file plus offset. + @@ -49,10 +55,11 @@ &reftitle.returnvalues; - Description... + Return &true; if the position was updated, &false; otherwise. + &reftitle.seealso; - Classname::Method + fseek diff --git a/reference/stream/streamwrapper/stream-set-option.xml b/reference/stream/streamwrapper/stream-set-option.xml index 893b804c1a..d74ab7f5fd 100644 --- a/reference/stream/streamwrapper/stream-set-option.xml +++ b/reference/stream/streamwrapper/stream-set-option.xml @@ -1,5 +1,5 @@ - + @@ -10,17 +10,14 @@ &reftitle.description; - public voidstreamWrapper::stream_set_option - stringoption - stringarg1 - stringarg2 + public boolstreamWrapper::stream_set_option + intoption + intarg1 + intarg2 - The method description goes here. + This method is called to set options on the stream. - - &warn.undocumented.func; - @@ -31,7 +28,12 @@ option - Description... + One of: + + STREAM_OPTION_BLOCKING (The method was called in response to stream_set_blocking) + STREAM_OPTION_READ_TIMEOUT (The method was called in response to stream_set_timeout) + STREAM_OPTION_WRITE_BUFFER (The method was called in response to stream_set_write_buffer) + @@ -39,7 +41,12 @@ arg1 - Description... + If option is + + STREAM_OPTION_BLOCKING: requested blocking mode (1 meaning block 0 not blocking). + STREAM_OPTION_READ_TIMEOUT: the timeout in seconds. + STREAM_OPTION_WRITE_BUFFER: buffer mode (STREAM_BUFFER_NONE or STREAM_BUFFER_FULL). + @@ -47,7 +54,12 @@ arg2 - Description... + If option is + + STREAM_OPTION_BLOCKING: This option is not set. + STREAM_OPTION_READ_TIMEOUT: the timeout in microseconds. + STREAM_OPTION_WRITE_BUFFER: the requested buffer size. + @@ -58,10 +70,13 @@ &reftitle.returnvalues; - Description... + &return.success; + If option is not implemented, &false; should be + returned. + &reftitle.seealso; - Classname::Method + stream_set_blocking + stream_set_timeout + stream_set_write_buffer diff --git a/reference/stream/streamwrapper/stream-tell.xml b/reference/stream/streamwrapper/stream-tell.xml index aa04da2f7d..bee1a41b03 100644 --- a/reference/stream/streamwrapper/stream-tell.xml +++ b/reference/stream/streamwrapper/stream-tell.xml @@ -1,5 +1,5 @@ - + @@ -10,15 +10,12 @@ &reftitle.description; - public voidstreamWrapper::stream_tell + public intstreamWrapper::stream_tell - The method description goes here. + This method is called in response to ftell. - - &warn.undocumented.func; - @@ -29,10 +26,11 @@ &reftitle.returnvalues; - Description... + Should return the curren position of the stream. + &reftitle.seealso; - Classname::Method + ftell diff --git a/reference/stream/streamwrapper/stream-write.xml b/reference/stream/streamwrapper/stream-write.xml index 1cd6009f2d..309aa502ce 100644 --- a/reference/stream/streamwrapper/stream-write.xml +++ b/reference/stream/streamwrapper/stream-write.xml @@ -1,5 +1,5 @@ - + @@ -10,15 +10,18 @@ &reftitle.description; - public voidstreamWrapper::stream_write + public intstreamWrapper::stream_write stringdata - The method description goes here. + This method is called in response to fwrite. - - &warn.undocumented.func; - + + + Remember to update the current position of the stream by number of bytes + that were successfully written. + + @@ -29,8 +32,14 @@ data - Description... + Should be stored into the underlying stream. + + + If there is not enough room in the underlying stream, store as much as + possible. + + @@ -40,10 +49,12 @@ &reftitle.returnvalues; - Description... + Should return the number of bytes that were successfully stored, or 0 if + none could be stored. + &reftitle.seealso; - Classname::Method + fwrite diff --git a/reference/stream/versions.xml b/reference/stream/versions.xml index 95fda35887..eb9b4f6aeb 100644 --- a/reference/stream/versions.xml +++ b/reference/stream/versions.xml @@ -1,5 +1,5 @@ - + @@ -48,6 +48,27 @@ + + + + + + + + + + + + + + + + + + + + +