Podręcznik PHP
Poprzedni |  | Następny

# CIII. Stream functions

# Wprowadzenie

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 Dodatek J), 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 Rozdział 43. 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 Dodatek J 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 Dodatek J 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 Rozdział 43. 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 Dodatek J).

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.

# Instalacja

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.

# Predefiniowane stałe

Poniższe stałe są zdefiniowane w tym rozszerzeniu i stają się dostępne, gdy rozszerzenie jest dokompilowane do PHP, lub załadowane dynamicznie przy starcie.

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. 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. Server sockets should always include this flag.
`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 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.

# Przykłady

Przykład 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");
?>`

Przykład 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");
fputs($sock, "POST /form_action.php HTTP/1.0\r\n");
fputs($sock, "Host: secure.example.com\r\n");
fputs($sock, "Content-type: application/x-www-form-urlencoded\r\n");
fputs($sock, "Content-length: " . strlen($data) . "\r\n");
fputs($sock, "Accept: */*\r\n");
fputs($sock, "\r\n");
fputs($sock, "$data\r\n");
fputs($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);
?>`

Przykład 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); ?>`

Poprzedni | Spis treści | Następny
socket_writev | Początek rozdziału | stream_context_create