PHP: Stream Functions - Manual

downloads | documentation | faq | getting help | mailing lists | reporting bugs | php.net sites | links | conferences | my php.net

search for in the

stream_bucket_append stats_variance

Last updated: Sat, 27 Jan 2007

view this page in

# CLVII. Stream Functions

# Введение

Streams were introduced with PHP 4.3.0 as a way of generalizing file, network, data compression, and other operations which share a common set of functions and uses. In its simplest definition, a `stream` is a `resource` object which exhibits streamable behavior. That is, it can be read from or written to in a linear fashion, and may be able to fseek() to an arbitrary locations within the stream.

A `wrapper` is additional code which tells the stream how to handle specific protocols/encodings. For example, the `http` wrapper knows how to translate a URL into an `HTTP/1.0` request for a file on a remote server. There are many wrappers built into PHP by default (See Прил. M), and additional, custom wrappers may be added either within a PHP script using stream_wrapper_register(), or directly from an extension using the API Reference in Гл. 44. 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 of currently registered wrappers, use stream_get_wrappers().

A stream is referenced as: `scheme`://`target`

- `scheme`(string) - The name of the wrapper to be used. Examples include: file, http, https, ftp, ftps, compress.zlib, compress.bz2, and php. See Прил. M for a list of PHP builtin wrappers. If no wrapper is specified, the function default is used (typically `file`://).

- `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 Прил. M for a description of targets for builtin streams.

# Stream Filters

A `filter` is a final piece of code which may perform 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_filter_register() or in an extension using the API Reference in Гл. 44. To access the list of currently registered filters, use stream_get_filters().

# Stream Contexts

A `context` is a set of `parameters` and wrapper specific `options` which modify or enhance the behavior of a stream. `Contexts` are created using stream_context_create() and can be passed to most filesystem related stream creation functions (i.e. fopen(), file(), file_get_contents(), etc...).

`Options` can be specified when calling stream_context_create(), or later using stream_context_set_option(). A list of wrapper specific `options` can be found with the list of built-in wrappers (See Прил. M).

In addition, `parameters` may be set on a `context` using stream_context_set_params(). Currently the only `context parameter` supported by PHP is `notification`. The value of this parameter must be the name of a function to be called when an event occurs on a stream. The notification function called during an event should accept the following six parameters:

void my_notifier ( int notification_code, int severity, string message, int message_code, int bytes_transferred, int bytes_max )

`notification_code` and `severity` are numerical values which correspond to the `STREAM_NOTIFY_*` constants listed below. If a descriptive message is available from the stream, `message` and `message_code` will be populated with the appropriate values. The meaning of these values is dependent on the specific wrapper in use. `bytes_transferred` and `bytes_max` will be populated when applicable.

# Установка

Streams are an integral part of PHP as of version 4.3.0. No steps are required to enable them.

# Stream Classes

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_filter_register() for details on implementing user defined filters.

# Предопределенные константы

Перечисленные ниже константы определены данным расширением и могут быть доступны только в том случае, если PHP был собран с поддержкой этого расширения или же в том случае, если данное расширение подгружается во время выполнения.

Constant | Description
--- | ---
`STREAM_FILTER_READ` * | Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when reading
`STREAM_FILTER_WRITE` * | Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when writing
`STREAM_FILTER_ALL` * | This constant is equivalent to ``STREAM_FILTER_READ` | `STREAM_FILTER_WRITE``
`PSFS_PASS_ON` * | `Return Code` indicating that the userspace filter returned buckets in `$out`.
`PSFS_FEED_ME` * | `Return Code` indicating that the userspace filter did not return buckets in `$out` (i.e. No data available).
`PSFS_ERR_FATAL` * | `Return Code` indicating that the userspace filter encountered an unrecoverable error (i.e. Invalid data received).
`STREAM_USE_PATH` | `Flag` indicating if the `stream` used the include path.
`STREAM_REPORT_ERRORS` | `Flag` indicating if the `wrapper` is responsible for raising errors using trigger_error() during opening of the stream. If this flag is not set, you should not raise any errors.
`STREAM_CLIENT_ASYNC_CONNECT` * | Open client socket asynchronously. This option must be used together with the `STREAM_CLIENT_CONNECT` flag. Used with stream_socket_client().
`STREAM_CLIENT_CONNECT` * | Open client socket connection. Client sockets should always include this flag. Used with stream_socket_client().
`STREAM_CLIENT_PERSISTENT` * | Client socket opened with stream_socket_client() should remain persistent between page loads.
`STREAM_SERVER_BIND` * | Tells a stream created with stream_socket_server() to bind to the specified target. Server sockets should always include this flag.
`STREAM_SERVER_LISTEN` * | Tells a stream created with stream_socket_server() and bound using the `STREAM_SERVER_BIND` flag to start listening on the socket. Connection-orientated transports (such as TCP) must use this flag, otherwise the server socket will not be enabled. Using this flag for connect-less transports (such as UDP) is an error.
`STREAM_NOTIFY_RESOLVE` * | A remote address required for this stream has been resolved, or the resolution failed. See `severity` for an indication of which happened.
`STREAM_NOTIFY_CONNECT` | A connection with an external resource has been established.
`STREAM_NOTIFY_AUTH_REQUIRED` | Additional authorization is required to access the specified resource. Typical issued with `severity` level of `STREAM_NOTIFY_SEVERITY_ERR`.
`STREAM_NOTIFY_MIME_TYPE_IS` | The `mime-type` of resource has been identified, refer to `message` for a description of the discovered type.
`STREAM_NOTIFY_FILE_SIZE_IS` | The `size` of the resource has been discovered.
`STREAM_NOTIFY_REDIRECTED` | The external resource has redirected the stream to an alternate location. Refer to `message`.
`STREAM_NOTIFY_PROGRESS` | Indicates current progress of the stream transfer in `bytes_transferred` and possibly `bytes_max` as well.
`STREAM_NOTIFY_COMPLETED` * | There is no more data available on the stream.
`STREAM_NOTIFY_FAILURE` | A generic error occurred on the stream, consult `message` and `message_code` for details.
`STREAM_NOTIFY_AUTH_RESULT` | Authorization has been completed (with or without success).
`STREAM_NOTIFY_SEVERITY_INFO` | Normal, non-error related, notification.
`STREAM_NOTIFY_SEVERITY_WARN` | Non critical error condition. Processing may continue.
`STREAM_NOTIFY_SEVERITY_ERR` | A critical error occurred. Processing cannot continue.
`STREAM_IPPROTO_ICMP` + | Provides a ICMP socket.
`STREAM_IPPROTO_IP` + | Provides a IP socket.
`STREAM_IPPROTO_RAW` + | Provides a RAW socket.
`STREAM_IPPROTO_TCP` + | Provides a TCP socket.
`STREAM_IPPROTO_UDP` + | Provides a UDP socket.
`STREAM_PF_INET` + | Internet Protocol Version 4 (IPv4).
`STREAM_PF_INET6` + | Internet Protocol Version 6 (IPv6).
`STREAM_PF_UNIX` + | Unix system internal protocols.
`STREAM_SOCK_DGRAM` + | Provides datagrams, which are connectionless messages (UDP, for example).
`STREAM_SOCK_RAW` + | Provides a raw socket, which provides access to internal network protocols and interfaces. Usually this type of socket is just available to the root user.
`STREAM_SOCK_RDM` + | Provides a RDM (Reliably-delivered messages) socket.
`STREAM_SOCK_SEQPACKET` + | Provides a sequenced packet stream socket.
`STREAM_SOCK_STREAM` + | Provides sequenced, two-way byte streams with a transmission mechanism for out-of-band data (TCP, for example).
`STREAM_SHUT_RD` | Used with stream_socket_shutdown() to disable further receptions. Added in PHP 5.2.1.
`STREAM_SHUT_WR` | Used with stream_socket_shutdown() to disable further transmissions. Added in PHP 5.2.1.
`STREAM_SHUT_RDWR` | Used with stream_socket_shutdown() to disable further receptions and transmissions. Added in PHP 5.2.1.

> Замечание: The constants marked with `*` are just available since PHP 5.0.0.

> Замечание: The constants marked with `+` are available since PHP 5.1.0 and are meant to be used with stream_socket_pair(). Please note that some of these constants might not be available in your system.

# Stream Errors

As with any file or socket related function, an operation 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 array returned by stream_get_wrappers() for a list of streams supported by your installation of PHP. As with most PHP internal functions if a failure occurs an `E_WARNING` message will be generated describing the nature of the error.

# Примеры

Пример 1. Using file_get_contents() to retrieve data from multiple sources

`<?php
/* Read local file from /home/bar */
$localfile = file_get_contents("/home/bar/foo.txt");
/* Identical to above, explicitly naming FILE scheme */
$localfile = file_get_contents("file:///home/bar/foo.txt");
/* Read remote file from www.example.com using HTTP */
$httpfile = file_get_contents("http://www.example.com/foo.txt");
/* Read remote file from www.example.com using HTTPS */
$httpsfile = file_get_contents("https://www.example.com/foo.txt");
/* Read remote file from ftp.example.com using FTP */
$ftpfile = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt");
/* Read remote file from ftp.example.com using FTPS */
$ftpsfile = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt");
?>`

Пример 2. Making a POST request to an https server

`<?php
/* Send POST request to https://secure.example.com/form_action.php
* Include form elements named "foo" and "bar" with dummy values
*/
$sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30);
if (!$sock) die("$errstr ($errno)\n");
$data = "foo=" . urlencode("Value for Foo") . "&bar=" . urlencode("Value for Bar");
fwrite($sock, "POST /form_action.php HTTP/1.0\r\n");
fwrite($sock, "Host: secure.example.com\r\n");
fwrite($sock, "Content-type: application/x-www-form-urlencoded\r\n");
fwrite($sock, "Content-length: " . strlen($data) . "\r\n");
fwrite($sock, "Accept: */*\r\n");
fwrite($sock, "\r\n");
fwrite($sock, "$data\r\n");
fwrite($sock, "\r\n");
$headers = "";
while ($str = trim(fgets($sock, 4096)))
$headers .= "$str\n";
echo "\n";
$body = "";
while (!feof($sock))
$body .= fgets($sock, 4096);
fclose($sock);
?>`

Пример 3. Writing data to a compressed file

`<?php
/* Create a compressed file containing an arbitrarty string
* File can be read back using compress.zlib stream or just
* decompressed from the command line using 'gzip -d foo-bar.txt.gz'
*/
$fp = fopen("compress.zlib://foo-bar.txt.gz", "wb");
if (!$fp) die("Unable to create file.");
fwrite($fp, "This is a test.\n");
fclose($fp);
?>`

add a note User Contributed Notes
Stream Functions
marcus at synchromedia dot co dot uk
30-Oct-2006 10:16
`As this article says, there is no quoted_printable_encode function() in PHP: http://www.zend.com/manual/filters.convert.php
However there is a stream filter for quoted printable encoding. Here's an example function that produces output suitable for email and doesn't explicitly use external files (though it might do for strings over 2Mb due to the nature of the temp stream type):
<?php
function quoted_printable_encode($string) {
$fp = fopen('php://temp/', 'r+');
$params = array('line-length' => 70, 'line-break-chars' => "\r\n");
stream_filter_append($fp, 'convert.quoted-printable-encode', STREAM_FILTER_READ, $params);
fputs($fp, $string);
rewind($fp);
return stream_get_contents($fp);
}
echo quoted_printable_encode(str_repeat("hello there ", 50)." a=1\r\n")."\n";
?>
The filter needs to be restricted to STREAM_FILTER_READ because by default it will get filtered both going into and out of the stream, and will thus get encoded twice.
It should be much faster than using a PHP implementation of the same thing, though note that this will only work in PHP 5.1+.`
jausions at php dot net
15-May-2006 08:59
`For the "notification" index of the $params for stream_context_set_params() function, a callable function is accepted. That is array(&$object, 'methodName') will also work.`
add a note
stream_bucket_append stats_variance

Last updated: Sat, 27 Jan 2007
show source | credits | stats | sitemap | contact | advertising | mirror sites
Copyright © 2001-2007 The PHP Group
All rights reserved.
This mirror generously provided by: Yahoo! Inc.
Last updated: Sat Mar 10 11:33:19 2007 PST