PHP Function Reference

PHP - Streams



Streams are the 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 location 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.

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. 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.

Installation

There is no installation needed to use these functions. These functions are part of the PHP core.

Runtime Configuration

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

PHP php_user_filter Class

Class Description
php_user_filter The php_user_filter class.
MethodsDescription
filter() Called when applying the filter.
onClose() Called when closing the filter.
onCreate() Called when creating the filter.

PHP streamWrapper Class

Class Description
streamWrapper The streamWrapper class.
MethodsDescription
__construct() Constructs a new stream wrapper.
__destruct() Destructs an existing stream wrapper.
dir_closedir() Closes directory handle.
dir_opendir() Opens directory handle.
dir_readdir() Reads entry from directory handle.
dir_rewinddir() Rewinds directory handle.
rename() Renames a file or directory.
mkdir() Creates a directory.
rmdir() Removes a directory.
stream_cast() Retrieves the underlying resource.
stream_close() Close a resource.
stream_eof() Tests for end-of-file on a file pointer.
stream_flush() Flushes the output.
stream_lock() Advisory file locking.
stream_metadata() Changes stream metadata.
stream_open() Opens file or URL.
stream_read() Reads from stream.
stream_seek() Seeks to specific location in a stream.
stream_set_option() Change stream options.
stream_stat() Retrieves information about a file resource.
stream_tell() Retrieves the current position of a stream.
stream_truncate() Truncates stream.
stream_write() Writes to stream.
unlink() Deletes a file.
url_stat() Retrieves information about a file.

PHP Stream Functions

FunctionsDescription
stream_bucket_append() Appends bucket to brigade.
stream_bucket_make_writeable() Returns a bucket object from the brigade for operating on.
stream_bucket_new() Creates a new bucket for use on the current stream.
stream_bucket_prepend() Prepends bucket to brigade.
stream_context_create() Creates a stream context.
stream_context_get_default() Retrieves the default stream context.
stream_context_get_options() Retrieves options for a stream/wrapper/context.
stream_context_get_params() Retrieves parameters from a context.
stream_context_set_default() Sets the default stream context.
stream_context_set_option() Sets an option for a stream/wrapper/context.
stream_context_set_params() Set parameters for a stream/wrapper/context.
stream_copy_to_stream() Copies data from one stream to another.
stream_filter_append() Attaches a filter to a stream.
stream_filter_prepend() Attaches a filter to a stream.
stream_filter_register() Registers a user defined stream filter.
stream_filter_remove() Removes a filter from a stream.
stream_get_contents() Reads remainder of a stream into a string.
stream_get_filters() Retrieves list of registered filters.
stream_get_line() Gets line from stream resource up to a given delimiter.
stream_get_meta_data() Retrieves header/meta data from streams/file pointers.
stream_get_transports() Retrieves list of registered socket transports.
stream_get_wrappers() Retrieves list of registered streams.
stream_is_local() Checks if a stream is a local stream.
stream_isatty() Checks if a stream is a TTY.
stream_notification_callback() A callback function for the notification context parameter.
stream_register_wrapper() Registers a URL wrapper implemented as a PHP class. Alias of stream_wrapper_register() function.
stream_resolve_include_path() Resolves filename against the include path.
stream_select() Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec.
stream_set_blocking() Sets blocking/non-blocking mode on a stream.
stream_set_chunk_size() Sets the stream chunk size.
stream_set_read_buffer() Sets read file buffering on the given stream.
stream_set_timeout() Sets timeout period on a stream.
stream_set_write_buffer() Sets write file buffering on the given stream.
stream_socket_accept() Accepts a connection on a socket created by stream_socket_server.
stream_socket_client() Opens Internet or Unix domain socket connection.
stream_socket_enable_crypto() Turns encryption on/off on an already connected socket.
stream_socket_get_name() Retrieves the name of the local or remote sockets.
stream_socket_pair() Creates a pair of connected, indistinguishable socket streams.
stream_socket_recvfrom() Receives data from a socket, connected or not.
stream_socket_sendto() Sends a message to a socket, whether it is connected or not.
stream_socket_server() Creates an Internet or Unix domain server socket.
stream_socket_shutdown() Shutdown a full-duplex connection.
stream_supports_lock() Tells whether the stream supports locking.
stream_wrapper_register() Registers a URL wrapper implemented as a PHP class.
stream_wrapper_restore() Restores a previously unregistered built-in wrapper.
stream_wrapper_unregister() Unregisters a URL wrapper.

PHP Streams Predefined Constants

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.

ConstantsDescription
STREAM_FILTER_READUsed with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when reading
STREAM_FILTER_WRITEUsed with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when writing
STREAM_FILTER_ALLThis constant is equivalent to STREAM_FILTER_READ | STREAM_FILTER_WRITE
PSFS_PASS_ONReturn Code indicating that the userspace filter returned buckets in $out.
PSFS_FEED_MEReturn Code indicating that the userspace filter did not return buckets in $out (i.e. No data available).
PSFS_ERR_FATALReturn Code indicating that the userspace filter encountered an unrecoverable error (i.e. Invalid data received).
PSFS_FLAG_NORMALRegular read/write.
PSFS_FLAG_FLUSH_INCAn incremental flush.
PSFS_FLAG_FLUSH_CLOSEFinal flush prior to closing.
STREAM_USE_PATHFlag indicating if the stream used the include path.
STREAM_REPORT_ERRORSFlag 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_CONNECTOpen client socket asynchronously. This option must be used together with the STREAM_CLIENT_CONNECT flag. Used with stream_socket_client().
STREAM_CLIENT_CONNECTOpen client socket connection. Client sockets should always include this flag. Used with stream_socket_client().
STREAM_CLIENT_PERSISTENTClient socket opened with stream_socket_client() should remain persistent between page loads.
STREAM_SERVER_BINDTells a stream created with stream_socket_server() to bind to the specified target. Server sockets should always include this flag.
STREAM_SERVER_LISTENTells 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.
STREAM_NOTIFY_RESOLVEA remote address required for this stream has been resolved, or the resolution failed. See severity for an indication of which happened.
STREAM_NOTIFY_CONNECTA connection with an external resource has been established.
STREAM_NOTIFY_AUTH_REQUIREDAdditional authorization is required to access the specified resource. Typical issued with severity level of STREAM_NOTIFY_SEVERITY_ERR.
STREAM_NOTIFY_MIME_TYPE_ISThe mime-type of resource has been identified, refer to message for a description of the discovered type.
STREAM_NOTIFY_FILE_SIZE_ISThe size of the resource has been discovered.
STREAM_NOTIFY_REDIRECTEDThe external resource has redirected the stream to an alternate location. Refer to message.
STREAM_NOTIFY_PROGRESSIndicates current progress of the stream transfer in bytes_transferred and possibly bytes_max as well.
STREAM_NOTIFY_COMPLETEDThere is no more data available on the stream.
STREAM_NOTIFY_FAILUREA generic error occurred on the stream, consult message and message_code for details.
STREAM_NOTIFY_AUTH_RESULTAuthorization has been completed (with or without success).
STREAM_NOTIFY_SEVERITY_INFONormal, non-error related, notification.
STREAM_NOTIFY_SEVERITY_WARNNon critical error condition. Processing may continue.
STREAM_NOTIFY_SEVERITY_ERRA critical error occurred. Processing cannot continue.
STREAM_IPPROTO_ICMPProvides a ICMP socket. Used with stream_socket_pair() function.
STREAM_IPPROTO_IPProvides a IP socket. Used with stream_socket_pair() function.
STREAM_IPPROTO_RAWProvides a RAW socket. Used with stream_socket_pair() function.
STREAM_IPPROTO_TCPProvides a TCP socket. Used with stream_socket_pair() function.
STREAM_IPPROTO_UDPProvides a UDP socket. Used with stream_socket_pair() function.
STREAM_PF_INETInternet Protocol Version 4 (IPv4). Used with stream_socket_pair() function.
STREAM_PF_INET6Internet Protocol Version 6 (IPv6). Used with stream_socket_pair() function.
STREAM_PF_UNIXUnix system internal protocols. Used with stream_socket_pair() function.
STREAM_SOCK_DGRAMProvides datagrams, which are connection-less messages (UDP, for example). Used with stream_socket_pair() function.
STREAM_SOCK_RAWProvides a raw socket, which provides access to internal network protocols and interfaces. Usually this type of socket is just available to the root user. Used with stream_socket_pair() function.
STREAM_SOCK_RDMProvides a RDM (Reliably-delivered messages) socket. Used with stream_socket_pair() function.
STREAM_SOCK_SEQPACKETProvides a sequenced packet stream socket. Used with stream_socket_pair() function.
STREAM_SOCK_STREAMProvides sequenced, two-way byte streams with a transmission mechanism for out-of-band data (TCP, for example). Used with stream_socket_pair() function.
STREAM_SHUT_RDUsed with stream_socket_shutdown() to disable further receptions.
STREAM_SHUT_WRUsed with stream_socket_shutdown() to disable further transmissions.
STREAM_SHUT_RDWRUsed with stream_socket_shutdown() to disable further receptions and transmissions.
STREAM_CAST_FOR_SELECTStream casting, for when stream_select() is calling stream_cast().
STREAM_CAST_AS_STREAMStream casting, when stream_cast() is called otherwise (see above).
STREAM_META_TOUCHUsed with stream_metadata(), to specify touch() call.
STREAM_META_OWNERUsed with stream_metadata(), to specify chown() call.
STREAM_META_OWNER_NAMEUsed with stream_metadata(), to specify chown() call.
STREAM_META_GROUPUsed with stream_metadata(), to specify chgrp() call.
STREAM_META_GROUP_NAMEUsed with stream_metadata(), to specify chgrp() call.
STREAM_META_ACCESSUsed with stream_metadata(), to specify chmod() call.
STREAM_BUFFER_NONENo buffering.
STREAM_BUFFER_LINELine buffering.
STREAM_BUFFER_FULLFull buffering.

5