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. |
| Methods | Description |
| 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. |
| Methods | Description |
| __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
| Functions | Description |
|---|---|
| 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.
| Constants | Description |
|---|---|
| STREAM_FILTER_READ | Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when reading |
| STREAM_FILTER_WRITE | Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when writing |
| STREAM_FILTER_ALL | This constant is equivalent to STREAM_FILTER_READ | STREAM_FILTER_WRITE |
| PSFS_PASS_ON | Return Code indicating that the userspace filter returned buckets in $out. |
| PSFS_FEED_ME | Return Code indicating that the userspace filter did not return buckets in $out (i.e. No data available). |
| PSFS_ERR_FATAL | Return Code indicating that the userspace filter encountered an unrecoverable error (i.e. Invalid data received). |
| PSFS_FLAG_NORMAL | Regular read/write. |
| PSFS_FLAG_FLUSH_INC | An incremental flush. |
| PSFS_FLAG_FLUSH_CLOSE | Final flush prior to closing. |
| 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_CLIENT_ASYNC_CONNECT | Open client socket asynchronously. This option must be used together with the STREAM_CLIENT_CONNECT flag. Used with stream_socket_client(). |
| STREAM_CLIENT_CONNECT | Open client socket connection. Client sockets should always include this flag. Used with stream_socket_client(). |
| STREAM_CLIENT_PERSISTENT | Client socket opened with stream_socket_client() should remain persistent between page loads. |
| STREAM_SERVER_BIND | Tells a stream created with stream_socket_server() to bind to the specified target. Server sockets should always include this flag. |
| STREAM_SERVER_LISTEN | 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. |
| STREAM_NOTIFY_RESOLVE | A remote address required for this stream has been resolved, or the resolution failed. See severity for an indication of which happened. |
| STREAM_NOTIFY_CONNECT | A connection with an external resource has been established. |
| STREAM_NOTIFY_AUTH_REQUIRED | Additional authorization is required to access the specified resource. Typical issued with severity level of STREAM_NOTIFY_SEVERITY_ERR. |
| STREAM_NOTIFY_MIME_TYPE_IS | The mime-type of resource has been identified, refer to message for a description of the discovered type. |
| STREAM_NOTIFY_FILE_SIZE_IS | The size of the resource has been discovered. |
| STREAM_NOTIFY_REDIRECTED | The external resource has redirected the stream to an alternate location. Refer to message. |
| STREAM_NOTIFY_PROGRESS | Indicates current progress of the stream transfer in bytes_transferred and possibly bytes_max as well. |
| STREAM_NOTIFY_COMPLETED | There is no more data available on the stream. |
| STREAM_NOTIFY_FAILURE | A generic error occurred on the stream, consult message and message_code for details. |
| STREAM_NOTIFY_AUTH_RESULT | Authorization has been completed (with or without success). |
| STREAM_NOTIFY_SEVERITY_INFO | Normal, non-error related, notification. |
| STREAM_NOTIFY_SEVERITY_WARN | Non critical error condition. Processing may continue. |
| STREAM_NOTIFY_SEVERITY_ERR | A critical error occurred. Processing cannot continue. |
| STREAM_IPPROTO_ICMP | Provides a ICMP socket. Used with stream_socket_pair() function. |
| STREAM_IPPROTO_IP | Provides a IP socket. Used with stream_socket_pair() function. |
| STREAM_IPPROTO_RAW | Provides a RAW socket. Used with stream_socket_pair() function. |
| STREAM_IPPROTO_TCP | Provides a TCP socket. Used with stream_socket_pair() function. |
| STREAM_IPPROTO_UDP | Provides a UDP socket. Used with stream_socket_pair() function. |
| STREAM_PF_INET | Internet Protocol Version 4 (IPv4). Used with stream_socket_pair() function. |
| STREAM_PF_INET6 | Internet Protocol Version 6 (IPv6). Used with stream_socket_pair() function. |
| STREAM_PF_UNIX | Unix system internal protocols. Used with stream_socket_pair() function. |
| STREAM_SOCK_DGRAM | Provides datagrams, which are connection-less messages (UDP, for example). Used with stream_socket_pair() function. |
| STREAM_SOCK_RAW | 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. Used with stream_socket_pair() function. |
| STREAM_SOCK_RDM | Provides a RDM (Reliably-delivered messages) socket. Used with stream_socket_pair() function. |
| STREAM_SOCK_SEQPACKET | Provides a sequenced packet stream socket. Used with stream_socket_pair() function. |
| STREAM_SOCK_STREAM | Provides 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_RD | Used with stream_socket_shutdown() to disable further receptions. |
| STREAM_SHUT_WR | Used with stream_socket_shutdown() to disable further transmissions. |
| STREAM_SHUT_RDWR | Used with stream_socket_shutdown() to disable further receptions and transmissions. |
| STREAM_CAST_FOR_SELECT | Stream casting, for when stream_select() is calling stream_cast(). |
| STREAM_CAST_AS_STREAM | Stream casting, when stream_cast() is called otherwise (see above). |
| STREAM_META_TOUCH | Used with stream_metadata(), to specify touch() call. |
| STREAM_META_OWNER | Used with stream_metadata(), to specify chown() call. |
| STREAM_META_OWNER_NAME | Used with stream_metadata(), to specify chown() call. |
| STREAM_META_GROUP | Used with stream_metadata(), to specify chgrp() call. |
| STREAM_META_GROUP_NAME | Used with stream_metadata(), to specify chgrp() call. |
| STREAM_META_ACCESS | Used with stream_metadata(), to specify chmod() call. |
| STREAM_BUFFER_NONE | No buffering. |
| STREAM_BUFFER_LINE | Line buffering. |
| STREAM_BUFFER_FULL | Full buffering. |
