Object-oriented I/O facility
Object-oriented I/O facility
Source objects (objects implementing
SourceInterface) can be used to read raw chunks of data from several sources :
StringSources can be used to read data from a string ;
StreamSources can be used to read data from a PHP stream resource, without protection from most flaws in the implementation of the wrapped PHP stream ; they can also be used as
Sinks (read more in the next section) if the stream is writable or bidirectional ;
BufferedSources can be used to wrap other sources, in order to fix several flaws which their implementation may have, and add missing features (for example, haven't you already needed, if only once, to seek backwards on a socket ?) ;
OuterSources are abstract : you may extend them to provide additional services on existing
Sources (for example,
You may create
Sources directly from the classes' constructors, or using static methods from the
Source class, which may provide additional services (for example,
fromFile automatically wrap the
BufferedSources by default).
Source class also provides static utility methods.
Sink objects (objects implementing
SinkInterface) can be used to write raw chunks of data to several sinks :
StringSinks can be used to build strings (but may be slower than plain concatenation : beware of call overhead !) ;
SystemSinkis a simple wrapper for
echo; it is a singleton ;
RecordFunctionSinks can be used to aggregate data into records (of fixed size, or delimited by a separator, with an optional size limit) and pass them to a custom function ;
StreamSources (see the previous section) which wrap a writable or bidirectional stream can be used to write data to a PHP stream resource ;
TeeSinks can be used to duplicate data into multiple
Source class, the
Sink class provides static methods which can be used to easily create
Sinks, and static utility methods.
State objects (objects implementing
StateInterface) can be obtained by calling
captureState on a
Source which supports it.
They can be used to rewind the
Source to a previous position using the
You can wrap your
Source in a
BufferedSource if you need to rewind it and if it doesn't support it.
Reader objects (which do not implement any specific interface, as they provide much different services) can be used to read structured data from
CDataReaders can be used to ease the writing of lexers : they support
eating fixed strings, strings including or excluding only given character classes, and white space ;
CDataReaders optimized for
StringSources, which additionally suppport
eating strings matching a regular expression (using
SerializedReaders can be used to separate concatenated
serialized values (as in
serialize($foo).serialize($bar)), regardless of whether they come from a local
Source(such as a string or a file stream) or a remote one (such as a pipe or network stream) ; they are explicitly designed to work efficiently with remote
JsonReaders can be used to separate concatenated JSON (as specified by RFC 7159) values, in the same conditions as
It is recommended to create
CDataReaders using the
fromSource static method : it will automatically prefer an optimized implementation (such as
StringCDataReader) when applicable.
Channel objects (objects implementing
ChannelInterface) can be used to communicate with remote tasks using messages, which will be serialized if necessary :
SerializedChannels serialize the messages using the native PHP format (with
JsonChannels serialize the messages using JSON (as specified by RFC 7159).
ChannelFactory objects (objects implementing
ChannelFactoryInterface) can be used by an application or a library to specify an encoder/decoder couple, along with their parameters, to another library.
Selectable objects (objects implementing
SelectableInterface) are objects which wrap PHP streams. They can be passed to the static methods of the
Selectable class, which are object-oriented wrappers to
stream_select. These methods can look for
Selectables wrapped in arbitrarily many
OuterSources, and will let the originally passed objects (not the inner
Selectables) in the sets on return.
Many objects are
Channels, and objects of the
Selectable class itself : in addition to its static utility methods, it provides a bare-bones implementation of the interface (which you can use to, for example, add a server socket to your set).