From c3196a11445d07a5edcaf4eef207817e259f028d Mon Sep 17 00:00:00 2001 From: Sara Golemon Date: Fri, 3 Jan 2003 02:41:14 +0000 Subject: [PATCH] Finish moving streams documentation to its own section... git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@110044 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../stream/functions/stream-get-meta-data.xml | 120 +++++++ .../functions/stream-register-wrapper.xml | 320 ++++++++++++++++++ .../stream/functions/stream-set-blocking.xml | 60 ++++ .../stream/functions/stream-set-timeout.xml | 81 +++++ .../functions/stream-set-write-buffer.xml | 76 +++++ reference/stream/reference.xml | 204 +++++++++++ 6 files changed, 861 insertions(+) create mode 100644 reference/stream/functions/stream-get-meta-data.xml create mode 100644 reference/stream/functions/stream-register-wrapper.xml create mode 100644 reference/stream/functions/stream-set-blocking.xml create mode 100644 reference/stream/functions/stream-set-timeout.xml create mode 100644 reference/stream/functions/stream-set-write-buffer.xml create mode 100644 reference/stream/reference.xml diff --git a/reference/stream/functions/stream-get-meta-data.xml b/reference/stream/functions/stream-get-meta-data.xml new file mode 100644 index 0000000000..9ac64494c4 --- /dev/null +++ b/reference/stream/functions/stream-get-meta-data.xml @@ -0,0 +1,120 @@ + + + + + stream_get_meta_data + Retrieves header/meta data from streams/file pointers + + + Description + + arrayfile_get_meta_data + resourcestream + + + Returns information about an existing stream. + The stream can be any stream created by fopen, + fsockopen and pfsockopen. + The result array contains the following items: + + + + + timed_out (bool) - &true; if the stream + timed out while waiting for data on the last call to + fread or fgets. + + + + + blocked (bool) - &true; if the stream is + in blocking IO mode. See socket_set_blocking. + + + + + eof (bool) - &true; if the stream has reached + end-of-file. Note that for socket streams this member can be &true; + even when unread_bytes is non-zero. To + determine if there is more data to be read, use + feof instead of reading this item. + + + + + unread_bytes (int) - the number of bytes + currently contained in the read buffer. + + + + + The following items were added in PHP 4.3: + + + + + stream_type (string) - a label describing + the underlying implementation of the stream. + + + + + wrapper_type (string) - a label describing + the protocol wrapper implementation layered over the stream. + See for more information about wrappers. + + + + + wrapper_data (mixed) - wrapper specific + data attached to this stream. See for + more information about wrappers and their wrapper data. + + + + + filters (array) - and array containing + the names of any filters that have been stacked onto this stream. + Filters are currently undocumented. + + + + + + This function was introduced in PHP 4.3, but prior to this version, + socket_get_status could be used to retrieve + the first four items, for socket based streams only. + + + In PHP 4.3 and later, + socket_get_status is an alias for this function. + + + + This function does NOT work on sockets created by the Socket extension. + + + + + + diff --git a/reference/stream/functions/stream-register-wrapper.xml b/reference/stream/functions/stream-register-wrapper.xml new file mode 100644 index 0000000000..42d5f3efdb --- /dev/null +++ b/reference/stream/functions/stream-register-wrapper.xml @@ -0,0 +1,320 @@ + + + + + + stream_register_wrapper + Register a URL wrapper implemented as a PHP class + + + Description + + booleanstream_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.). + + + 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. + + + + booleanstream_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. + + + + booleanstream_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. + + + + booleanstream_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. + + + + booleanstream_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); + +]]> + + + + + + + + + diff --git a/reference/stream/functions/stream-set-blocking.xml b/reference/stream/functions/stream-set-blocking.xml new file mode 100644 index 0000000000..0d004976e4 --- /dev/null +++ b/reference/stream/functions/stream-set-blocking.xml @@ -0,0 +1,60 @@ + + + + + + stream_set_blocking + Set blocking/non-blocking mode on a stream + + + Description + + boolstream_set_blocking + resourcestream + intmode + + + If mode is &false;, the given stream + will be switched to non-blocking mode, and if &true;, it + will be switched to blocking mode. This affects calls like + fgets and fread + that read from the stream. In non-blocking mode an + fgets call will always return right away + while in blocking mode it will wait for data to become available + on the stream. + + + This function was previously called as + set_socket_blocking and later + socket_set_blocking but this usage is deprecated. + + + + Prior to PHP 4.3, this function only worked on socket based streams. + Since PHP 4.3, this function works for any stream that supports + non-blocking mode (currently, regular files and socket streams). + + + + + + diff --git a/reference/stream/functions/stream-set-timeout.xml b/reference/stream/functions/stream-set-timeout.xml new file mode 100644 index 0000000000..2893857237 --- /dev/null +++ b/reference/stream/functions/stream-set-timeout.xml @@ -0,0 +1,81 @@ + + + + + + stream_set_timeout + Set timeout period on a stream + + + Description + + boolstream_set_timeout + resourcestream + intseconds + intmicroseconds + + + Sets the timeout value on stream, + expressed in the sum of seconds and + microseconds. + + <function>stream_set_timeout</function> Example + + +]]> + + + + + + As of PHP 4.3, this function can (potentially) work on any kind of + stream. In PHP 4.3, socket based streams are still the only kind + supported in the PHP core, although streams from other extensions + may support this function. + + + + This function was previously called as + set_socket_timeout and later + socket_set_timeout but this usage is deprecated. + + + See also: fsockopen and fopen. + + + + + diff --git a/reference/stream/functions/stream-set-write-buffer.xml b/reference/stream/functions/stream-set-write-buffer.xml new file mode 100644 index 0000000000..b883a1b40b --- /dev/null +++ b/reference/stream/functions/stream-set-write-buffer.xml @@ -0,0 +1,76 @@ + + + + + + stream_set_write_buffer + Sets file buffering on the given stream + + + Description + + intstream_set_write_buffer + resourcestream + intbuffer + + + Output using fwrite is normally buffered at + 8K. This means that if there are two processes wanting to write + to the same output stream (a file), each is paused after 8K of + data to allow the other to write. + stream_set_write_buffer + sets the buffering for write operations on the given filepointer + stream to buffer bytes. + If buffer is 0 then write operations are + unbuffered. This ensures that all writes with + fwrite are completed before other processes + are allowed to write to that output stream. + + + The function returns 0 on success, or EOF if the request cannot + be honored. + + + The following example demonstrates how to use + stream_set_write_buffer to create an unbuffered stream. + + <function>stream_set_write_buffer</function> example + + + + + + + + See also fopen and fwrite. + + + + + diff --git a/reference/stream/reference.xml b/reference/stream/reference.xml new file mode 100644 index 0000000000..b735759df5 --- /dev/null +++ b/reference/stream/reference.xml @@ -0,0 +1,204 @@ + + + + Stream functions + Streams + + + +
+ &reftitle.intro; + + Streams were introduced with PHP 4.3.0 as + a way of generalizing file, network, data compression, and other + opperations which share a common set of functions and uses. In + its simplest definition, a stream is any I/O conduit for exchanging + information. Some streams work on the local filesystem, some + use network connections (sockets), while others might potentially focus + on communication devices such as printers or modems. Because any variety + of stream may be added to PHP via the + stream_register_wrapper function, there is no + set limit on what can be done with them. See + for a listing of stream wrappers built into PHP. + + + A stream is referenced as: scheme://target + + + + scheme(string) - + The name of the stream wrapper to be used. Examples include: file, + http, https, ftp, ftps, compress.zlib, compress.bz2, ssl, tls, and php. See + for a list of PHP builtin wrappers. + + + + + target - + Depends on the wrapper used. For filesystem related streams this is + typically a path and filename of the desired file. For network related + streams this is typically a hostname often with a path appended. Again, see + for a description of targets for builtin streams. + + + + + + Filters may also be applied to streams to further process data on its + way into or out of a stream related call. Documentation on this + functionality is comming soon. + +
+ +
+ &reftitle.required; + &no.requirement; +
+ +
+ &reftitle.install; + + Streams are an integral part of PHP + as of version 4.3.0. No steps are required to enable them. + +
+ +
+ &reftitle.runtime; + &no.config; +
+ +
+ &reftitle.resources; + &no.resource; +
+ +
+ &reftitle.constants; + &no.constants; +
+ +
+ Stream Errors + + As with any file or socket related function, an opperation on a stream + may fail for a variety of normal reasons (i.e.: Unable to connect to remote + host, file not found, etc...). A stream related call may also fail because + the desired stream is not registered on the running system. See the output of + php_info for a list of streams supported by your + installation of PHP. As with most PHP internal functions + if a failure occours an E_WARNING message will be generated + describing the nature of the error. + +
+ +
+ &reftitle.examples; + + + Using file_get_contents() to retrieve data from multiple sources + + +]]?> + + + + + + Making a POST request to an https server + + +]]> + + + + + + Writting data to a compressed file + + +]]> + + + +
+ + For PHP Streams Development, See Also: + + + +&reference.stream.functions; + + + +