-
Notifications
You must be signed in to change notification settings - Fork 0
Docs Streams
Stubbles provides input and output streams for different kind of sources within the net::stubbles::streams package. All input streams implement the net::stubbles::streams::stubInputStream interface, all output streams the net::stubbles::streams::stubOutputStream interface. While input streams can be used to read data from a source, output streams can be used to write data to a certain source.
The input stream interface provides the following methods:
- read($length = 8192) - returns given amount of bytes
- readLine($length = 8192) - returns all characters up to given length until next line break
- bytesLeft() - returns the amount of bytes left to be read
- eof() - checks whether end of input was reached
- close() - closes the stream
The output stream interface provides the following methods:
- write($bytes) - writes given bytes and returns amount of written bytes
- writeLine($bytes) - same as write(), but adds a line break at end of bytes
- close() - closes the stream
Some streams are seekable which means you can go from one position in the stream to another. Input streams which are seekable implement the net::stubbles::streams::stubSeekable interface. It provides the following methods:
- seek($offset, $whence = stubSeekable::SET) - sets internal stream pointer to given position
- tell() - returns the current position of the internal stream pointer
To read data from a file one may use the net::stubbles::streams::file::stubFileInputStream class. Its constructor expects either a name of a file, or an already opened file pointer resource. If it is the name of the file the second parameter of the constructor sets the mode in which the file is opened, it defaults to rb (binary reading).
To write data to a file one may use the net::stubbles::streams::file::stubFileOutputStream class. Similarly to the file input stream class its constructor expects either a name of a file, or an already opened file pointer resource. If it is the name of the file the second parameter of the constructor sets the mode in which the file is opened, it defaults to wb (binary writing).
Warning: the mode parameter accepts modes which might not make any sense with the stream class - e.g. the input stream allows wb as value for the mode parameter, but then you can not read from the given file, and vice versa for the output stream.
The file input stream is a seekable stream.
Sometimes it is helpful if one can read or write data into memory. For such purposes the net::stubbles::streams::memory::stubMemoryInputStream and net::stubbles::streams::memory::stubMemoryOutputStream exist. While the memory input stream class expects the content to be read from as string parameter for its constructor, the memory output stream does not expect a value on construction, but offers an additional method getBuffer() which returns all data written to this stream so far.
The memory input stream is a seekable stream.
The net::stubbles::streams::memory package contains a stream wrapper class which "invents" the memory protocol. If loaded, one can use the normal file functions from PHP, but without files. With the memory stream wrapper you can fool classes relying on the file functions by writing the contents to memory://mydata, now you just to get the class to read the data from this URL. Example:
file_put_contents('memory://mydata', $xmlData);
$xmlUnserializer = new stubXMLUnserializer();
$data = $xmlUnserializer->unserializeFile('memory://mydata');
To be able to read and write from/to such URLs just make sure the net::stubbles::streams::memory::stubMemoryStreamWrapper is loaded. You do not need to call any methods on this class yourself.
Sometimes it is necessary to decode input stream data into the internal encoding of the application. While Stubbles' internal encoding is UTF-8, all data read from input streams should be UTF-8 itself or at least converted to UTF-8 before returned from the input stream. To ease this, the net::stubbles::streams::stubDecodingInputStream class decorates another input stream given as first parameter on construction, and tries to decode the data read from the decorated input stream from the stream encoding to UTF-8 using iconv(). However you need to specify the charset of the decorated input stream as second parameter to the constructor:
$decodingInputStream = new stubDecodingInputStream($encodedInputStream, 'iso-8859-1');
Of course there must be a possibility to write back into the correct encoding. For this, the net::stubbles::streams::stubEncodingOutputStream class can be used. It tries to convert from internal UTF-8 into the encoding of the decorated output stream using iconv().
$encodingOutputStream = new stubEncodingOutputStream($encodedOutputStream, 'iso-8859-1');
Not part of the net::stubbles::streams package itself but based on its infrastructure are the console related input and output streams in the net::stubbles::console package. For reading data from the command line the class net::stubbles::console::stubConsoleInputStream can be used. As it does not make any sense to have more than one instance of this class it provides a factory method that will always return the same instance (you can not create an instance using the new operator, as the constructor of this class is protected):
$consoleInputStream = stubConsoleInputStream::forIn();
For writing data to the command line, two output stream exists:
$out = stubConsoleOutputStream::forOut(); $err = stubConsoleOutputStream::forError();
While the first should be used to write normal data to the command line, the second can be used to write error messages to the command line. You can not create your own instance of net::stubbles::console::stubConsoleOutputStream as its constructor is protected.
For reference: the console streams use STDIN, STDOUT and STDERR.
The console streams try to recognize the environment in which they are in. If they are not in an environment where input or output data is UTF-8, they try to wrap themselves in the net::stubbles::streams::stubDecodingInputStream respectively the net::stubbles::streams::stubEncodingOutputStream so the user of the console streams does not have to care itself on such issues.