PHP Manual
Prev |  | Next

# XCVIII. Stream functions

# Introduction

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 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 Appendix I), and additional, custom wrappers may be added either within a PHP script using stream_register_wrapper(), or directly from an extension using the API Reference in Chapter 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 `filter` is a final piece of code which may perform opperations 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 API Reference in Chapter 43. To access the list of currently registered filters, use stream_get_filters().

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 Appendix I 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 Appendix I for a description of targets for builtin streams.

# Requirements

No external libraries are needed to build this extension.

# Installation

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

# Runtime Configuration

This extension has no configuration directives defined in `php.ini`.

# Stream Classes

User designed wrappers can be registered via stream_register_wrapper(), 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 user defined filters.

# Predefined Constants

Constant | Description
--- | ---
`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 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 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 occours an `E_WARNING` message will be generated describing the nature of the error.

# Examples

Example 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");
    ?>

Example 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-url-encoded\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";

    print "\n";

    $body = "";
    while (!feof($sock))
      $body .= fgets($sock, 4096);

    fclose($sock);
    ?>

Example 3. Writting 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);
    ?>

Prev | Home | Next
socket_writev | Up | stream_context_create