exsyst/io

This package is abandoned and no longer maintained. No replacement package was suggested.

Object-oriented I/O facility

0.2.0 2016-08-16 17:43 UTC

Requires

• php: >=5.5

Requires (Dev)

• phpunit/phpunit: ~4.8

Apache-2.0

• EXSyst

README

EXSyst I/O Component

Object-oriented I/O facility

Sources

The 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, BufferedSources and Readers are OuterSources).

You may create Sources directly from the classes' constructors, or using static methods from the Source class, which may provide additional services (for example, fromStream and fromFile automatically wrap the StreamSources in BufferedSources by default).

The Source class also provides static utility methods.

Sinks

The 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 !) ;
• The SystemSink is 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 Sinks.

Like the Source class, the Sink class provides static methods which can be used to easily create Sinks, and static utility methods.

States

The 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 restore method.

You can wrap your Source in a BufferedSource if you need to rewind it and if it doesn't support it.

Readers

The Reader objects (which do not implement any specific interface, as they provide much different services) can be used to read structured data from Sources :

• 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 ;
• StringCDataReaders are CDataReaders optimized for StringSources, which additionally suppport eating strings matching a regular expression (using preg_match) ;
• 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 Sources ;
• JsonReaders can be used to separate concatenated JSON (as specified by RFC 7159) values, in the same conditions as SerializedReader.

It is recommended to create CDataReaders using the fromSource static method : it will automatically prefer an optimized implementation (such as StringCDataReader) when applicable.

Channels

The 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 serialize) ;
• JsonChannels serialize the messages using JSON (as specified by RFC 7159).

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

Selectables

The 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 Selectable : StreamSources, all 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).