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.
wrapper is additional code which tells the stream how to handle
specific protocols/encodings. For example, the
wrapper knows how to translate a URL into an
request for a file on a remote server. There are many wrappers
built into PHP by default (See Appendix O, List of Supported Protocols/Wrappers),
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 ???.
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
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 ???. To access the list of currently
registered filters, use stream_get_filters().
context is a set of
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
A list of wrapper specific
options can be found with
the list of built-in wrappers (See Appendix O, List of Supported Protocols/Wrappers).
parameters may be set on a
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
notification_code and severity
are numerical values which correspond to the
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.
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.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
|Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when reading|
|Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when writing|
This constant is equivalent to
|Open client socket asynchronously. This option must be used
together with the |
|Open client socket connection. Client sockets should always include this flag. Used with stream_socket_client().|
|Client socket opened with stream_socket_client() should remain persistent between page loads.|
|Tells a stream created with stream_socket_server() to bind to the specified target. Server sockets should always include this flag.|
|Tells a stream created with stream_socket_server()
and bound using the |
|A remote address required for this stream has been resolved, or the resolution failed. See severity for an indication of which happened.|
|A connection with an external resource has been established.|
Additional authorization is required to access the specified resource.
Typical issued with severity level of
|The external resource has redirected the stream to an alternate location. Refer to message.|
|Indicates current progress of the stream transfer in bytes_transferred and possibly bytes_max as well.|
|There is no more data available on the stream.|
|A generic error occurred on the stream, consult message and message_code for details.|
|Authorization has been completed (with or without success).|
|Normal, non-error related, notification.|
|Non critical error condition. Processing may continue.|
|A critical error occurred. Processing cannot continue.|
|Provides a ICMP socket.|
|Provides a IP socket.|
|Provides a RAW socket.|
|Provides a TCP socket.|
|Provides a UDP socket.|
|Internet Protocol Version 4 (IPv4).|
|Internet Protocol Version 6 (IPv6).|
|Unix system internal protocols.|
|Provides datagrams, which are connectionless messages (UDP, for example).|
|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.|
|Provides a RDM (Reliably-delivered messages) socket.|
|Provides a sequenced packet stream socket.|
|Provides sequenced, two-way byte streams with a transmission mechanism for out-of-band data (TCP, for example).|
|Used with stream_socket_shutdown() to disable further receptions. Added in PHP 5.2.1.|
|Used with stream_socket_shutdown() to disable further transmissions. Added in PHP 5.2.1.|
|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
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.
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.
/* 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:firstname.lastname@example.org/foo.txt");
/* Read remote file from ftp.example.com using FTPS */
$ftpsfile = file_get_contents("ftps://user:email@example.com/foo.txt");
/* 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");
$headers = "";
while ($str = trim(fgets($sock, 4096)))
$headers .= "$str\n";
$body = "";
$body .= fgets($sock, 4096);
/* 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");
Table of Contents