stubbles / streams
Input- and OutputStreams.
Installs: 2 158
Dependents: 2
Suggesters: 0
Security: 0
Stars: 0
Watchers: 3
Forks: 1
Open Issues: 2
Requires
- php: ^8.2
Requires (Dev)
- ext-iconv: *
- bovigo/assert: ^8.0
- bovigo/callmap: ^8.0
- mikey179/vfsstream: ^1.6.11
- phpunit/phpunit: ^10.5
- stubbles/reflect: ^10.0
- stubbles/sequence: ^10.1
Suggests
- ext-iconv: For use in decoding and encoding stream decorators.
- stubbles/sequence: Easer iteration of input streams with lines() function.
README
Input- and OutputStreams.
Build status
Installation
stubbles/streams is distributed as Composer package. To install it as a dependency of your package use the following command:
composer require "stubbles/streams": "^10.0"
Requirements
stubbles/streams requires at least PHP 8.2.
For using encoding and decoding decorated streams the PHP extension iconv is required.
For the stubbles\streams\linesOf()
and stubbles\streams\nonEmptyLinesOf()
functions the package stubbles/sequence
is required.
Interfaces and methods
stubbles/streams provides input and output streams for different kind of
sources. All input streams implement the stubbles\streams\InputStream
interface, all output streams the stubbles\streams\OutputStream
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.
Interfaces and their methods
Input stream methods
The input stream interface provides the following methods:
read($length = 8192)
- returns given amount of bytesreadLine($length = 8192)
- returns all characters up to given length until next line breakbytesLeft()
- returns the amount of bytes left to be readeof()
- checks whether end of input was reachedclose()
- closes the stream
Output stream methods
The output stream interface provides the following methods:
write($bytes)
- writes given bytes and returns amount of written byteswriteLine($bytes)
- same aswrite()
, but adds a line break at end of bytesclose()
- closes the stream
Seekable streams
Some streams are seekable which means you can go from one position in the stream
to another. Input streams which are seekable implement the
stubbles\streams\Seekable
interface. It provides the following methods:
seek($offset, $whence = Seekable::SET)
- sets internal stream pointer to given positiontell()
- returns the current position of the internal stream pointer
Copy from input to output stream
Available since release 8.1.0
The shortcut function stubbles\streams\copy()
provides a simple way to copy everything what's
in an input stream to an output stream:
copy($in)->to($out);
Please note that copying starts at the offset where the input stream currently is located, and changes the offset of the input stream to the end of the stream. In case a non-seekable input stream is copied it can not return to its initial offset.
Decorating streams
Encoding-related streams
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
stubbles\streams\DecodingInputStream
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 DecodingInputStream($encodedInputStream, 'iso-8859-1');
Note: since release 9.0.0 a third parameter can be used to influence what the data is being encoded to. The default is still UTF-8.
Of course there must be a possibility to write back into the correct encoding.
For this, the stubbles\streams\EncodingOutputStream
class can be used. It
tries to convert from internal UTF-8 into the encoding of the decorated output
stream using iconv()
.
$encodingOutputStream = new EncodingOutputStream($encodedOutputStream, 'iso-8859-1');
Note: since release 9.0.0 a third parameter can be used to influence what the data is being encoded from. The default is still UTF-8.
File related streams
To read data from a file one may use the stubbles\streams\file\FileInputStream
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). The file input stream is a seekable stream.
To write data to a file one may use the stubbles\streams\file\FileOutputStream
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.
Memory streams
Sometimes it is helpful if one can read or write data into memory. For such
purposes the stubbles\streams\memory\MemoryInputStream
and
stubbles\streams\memory\MemoryOutputStream
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 buffer()
which returns all data written to
this stream so far. Additionally, casting the stubbles\streams\memory\MemoryOutputStream
to string will return the buffer (available since release 4.0.0).
The memory input stream is a seekable stream.
Filter streams
When reading from or writing data to a stream sometimes it may happen that not all data to read or not all data to be written is relevant for what you want to achieve. For example, a file you read may contain comment lines, and you don't want to ignore those comment lines. Normally, you would have the logic on what to ignore in your reading class:
while (!$inputStream->eof()) { $line = $inputStream->readLine(); if (substr(0, 1, $line) !== '#') { $this->processLine($line); } }
In this small example it may not be much work, but what if comment lines may
also start with //
or there may even be comments stretching over more than one
line as we have in PHP with /* comment over several lines ... */
. Now the
logic might get a bit to complicated at this point. Stream filters to the rescue:
$filterStream = new FilteredInputStream( $inputStream, function($line) { return substr($line, 0, 1) !== '#'; } ); while (!$filterStream->eof()) { $this->processLine($inputStream->readLine()); }
The second argument for stubbles\streams\filter\FilteredInputStream
can be any
callable
which accepts a string as argument and returns true
when this string
should be passed through, and false
when this string should be filtered. Please
note that you can't filter single characters from the passed string, only
characters as a whole.
The same applies to the stubbles\streams\filter\FilteredOutputStream
,
just that the filter is applied to the data that is written.
Input stream sequences
Because iterating over input streams with while
can be quite cumbersome,
stubbles/streams provides an input stream implementation which is also an
instance of \Iterator
.
$lines = new InputStreamIterator(new FileInputStream('somefile.txt')); foreach ($lines as $line { processLine($line); }
Each iteration step is a call to readLine()
of the decorated input stream.
Please note: when the decorated stream is not an instance of stubbles\streams\Seekable
it can be iterated only once, trying to rewind will do nothing.
Integration with stubbles/sequence
Optionally iteration can be even more enhanced when the package stubbles/sequence is available.
This allows to use two functions which return an instance of
stubbles\sequence\Sequence
that allow all sequence operation on an input
stream:
stubbles\streams\linesOf($input)
The input can either be an instance of stubbles\streams\InputStream
or a file
name.
$lines = linesOf('somefile.txt') ->filter(/* callable which filters */) ->map(/* callable which maps the line to other content */); foreach ($lines as $line) { processLine($line); }
stubbles\streams\nonEmptyLinesOf($input)
Same as above, but already filters all empty lines.