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

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