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 Appendix N),
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 Chapter 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
The name of the wrapper to be used. Examples include: file,
http, https, ftp, ftps, compress.zlib, compress.bz2, and php. See
Appendix N for a list of PHP built-in wrappers. If
no wrapper is specified, the function default is used (typically
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 N for a description of targets for built-in streams.
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 Chapter 44. To access the list of currently
registered filters, use stream_get_filters().
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...).
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
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.
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 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.
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 mime-type of resource has been identified,
refer to message for a description of the
The size of the resource has been discovered.
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
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
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).
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.
$body = ""; while (!feof($sock)) $body .= fgets($sock, 4096);
Example 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.");