Lines Matching full:stream
8 …<a href="https://travis-ci.org/hoaproject/stream"><img src="https://img.shields.io/travis/hoaproje…
9 …s://coveralls.io/github/hoaproject/stream?branch=master"><img src="https://img.shields.io/coverall…
10 …<a href="https://packagist.org/packages/hoa/stream"><img src="https://img.shields.io/packagist/dt/…
11 …<a href="https://hoa-project.net/LICENSE"><img src="https://img.shields.io/packagist/l/hoa/stream.…
19 # Hoa\Stream
23 …/documentation-hack_book-ff0066.svg)](https://central.hoa-project.net/Documentation/Library/Stream)
24 …](https://img.shields.io/badge/organisation-board-ff0066.svg)](https://waffle.io/hoaproject/stream)
29 * Stream manipulations: Open, close, auto-close, timeout, blocking
31 * Stream notifications: Depending of the stream wrapper, the
35 * Context: Allow to pass options and parameters to the stream
38 destination of a stream, useful for instance to encrypt/decrypt a
43 * Interfaces: One interface per capability a stream can offer.
51 [Learn more](https://central.hoa-project.net/Documentation/Library/Stream).
57 require [`hoa/stream`](https://packagist.org/packages/hoa/stream):
60 $ composer require hoa/stream '~1.0'
85 As a quick overview, we propose to discover what `Hoa\Stream` provides
86 in term of interfaces, i.e. stream capabilities. This is almost the
87 most important part of this library. Then, how to define a stream,
88 followed by how to use stream contexts. Events, listeners and
92 ### Interfaces, aka stream capabilities
94 This library defines several interfaces representing important stream
96 library, working with streams. It ensures the stream is typed and
98 `Hoa\Stream\IStream` namespace:
100 * `In`, to read from a stream, provides `read`, `readInteger`,
102 * `Out`, to write onto a stream, provides `write`, `writeArray`,
108 * `Lockable`, to lock a stream, provides `lock` and several
111 * `Pathable`, for path-based stream, provides `getBasename` and
113 * `Pointable`, to move the internal pointer of the stream if any,
115 * `Statable`, to get statistics about a stream, provides `getSize`,
117 * `Structural`, for a structural stream, i.e. a stream acting like a
122 Thus, if one only need to read from a stream, it will type the stream
123 with `Hoa\Stream\IStream\In`. It also allows an implementer to choose
124 what capabilities its stream will provide or not.
126 Finally, the highest interface is `Stream`, defining the `getStream`
127 method, that's all. That's the most undefined stream. All capabilities
130 ### Define a concrete stream
132 The main `Hoa\Stream\Stream` class is abstract. Two method
134 respectively to open a particular stream, and to close this particular
135 stream, for instance:
138 class BasicFile extends Hoa\Stream\Stream
140 protected function &_open($streamName, Hoa\Stream\Context $context = null)
164 That's all. This stream has no capability yet. Let's implement the
168 class BasicFile extends Hoa\Stream\Stream implements Hoa\Stream\IStream\In
188 The `Stream` capability is already implemented by the
189 `Hoa\Stream\Stream` class.
193 A context is represented by the `Hoa\Stream\Context` class. It
194 represents a set of options and parameters for the stream.
195 [See the options and parameters for the `http://` stream wrapper](http://php.net/context.http)
199 options/parameters of the stream.
205 $context = Hoa\Stream\Context::getInstance($contextId);
211 And thus, we can ask a stream to use this context based on the chosen
218 For the stream implementer, the `getOptions` and `getParameters`
219 methods on the `Hoa\Stream\Context` class will be useful to
227 A stream has some events, and several listeners. So far, listeners
228 mostly represent “stream notifications”.
230 2 events are registered: `hoa://Event/Stream/<streamName>` and
231 `hoa://Event/Stream/<streamName>:close-before`. Thus, for instance, to
232 execute a function before the `/path/to/file` stream closes, one
236 Hoa\Event\Event::getEvent('hoa://Event/Stream//path/to/file:close-before')->attach(
243 Remember that a stream is not necessarily a file. It can be a socket,
244 a WebSocket, a stringbuffer, any stream you have defined…
247 firing another event… There is no rule. The observed stream is still
250 This event is fired when calling the `Hoa\Stream\Stream::close`
254 an instance of our stream without opening it. This action is called
256 argument of the default `Hoa\Stream\Stream` constructor; `true` to
266 must manually call the `open` method to open the stream then. Between
267 the stream instanciation and the stream opening, we can attach new
270 Depending of the stream implementation, different listeners will be
272 —in the context of stream— refers to them as notifications. Let's take
273 an example with an HTTP stream:
277 'https://hoa-project.net/', // stream name
332 * `complete`, when the stream is complete (meaning can vary a lot here),
333 * `connect`, when the stream is connected (meaning can vary a lot here),
335 * `mimetype`, when the MIME-type of the stream is known,
337 * `redirect`, when the stream is redirected to another stream,
338 * `resolve`, when the stream is resolved (meaning can vary a lot here),
339 * `size`, when the size of the stream is known.
345 (see [the documentation](http://php.net/stream.constants)),
357 This is possible for the stream implementer to add more
364 A stream wrapper allows to declare schemes, like `hoa://` or
366 `cloud://`. Any stream wrapper can be used with native standard PHP
370 The `Hoa\Stream\Wrapper\Wrapper` class holds all methods to
375 Hoa\Stream\Wrapper\Wrapper::register('tmp', Tmp::class);
378 A wrapper must implement the `Hoa\Stream\Wrapper\IWrapper\IWrapper`
380 namespace: `Stream` and `File`.
382 The `Stream` interface requires to implement several methods related to a stream, such as:
400 The `File` interface requires to implement other methods related to stream acting as a file, such a…
417 A stream is like a pipe, with an input, and an output. This is
420 the `Hoa\Stream\Filter\Filter` class:
427 the form of a class extending the `Hoa\Stream\Filter\Basic` filter,
430 Once a filter is registered, we can apply it on a stream by using its
432 several filters can be applied on a stream, in a specific order, like
436 Finally, we use the stream as usual. A stream is not necessarily an
437 instance of `Hoa\Stream`, it can be any PHP stream resources. Passing
438 an `Hoa\Stream` instance will obviously unwraps to its underlying PHP
439 stream resource.
441 Let's implement a filter that changes the content of the stream into
445 class ToUpper extends Hoa\Stream\Filter\Basic
449 $iBucket = new Hoa\Stream\Bucket($in);
450 $oBucket = new Hoa\Stream\Bucket($out);
471 Hoa\Stream\Filter::register($filterName, ToUpper::class);
474 Then, we must apply the filter on a specific stream, so let's open a
475 stream, and append the filter:
479 Hoa\Stream\Filter::append($file, $filterName, Hoa\Stream\Filter::READ);
483 see its effect when reading on our stream, let's do it:
491 A filter is a low-level stream API. It integrates with all kind of
496 `Hoa\Stream\Filter\Filter::getRegistered` method will provide the list
499 The `Hoa\Stream\Filter\LateComputed` class is a special filter. It
500 calls its public `compute` method when the stream reaches its end. So
503 content of the stream. This is really a buffer. Why would it be
510 example the `instrument://` wrapper can prepend a filter to the stream
512 `Hoa\Stream\Wrapper\IWrapper\Stream` interface).
518 There are more to cover. `Hoa\Stream` supports composite streams (with
519 the `Hoa\Stream\Composite` abstract class), i.e. streams embedding
522 An XML stream reads and writes from another inner stream (a file, a
525 allows a string to be manipulated with a stream API, so the stream
526 content is written on the disk. Stream capabiilities are not the same
532 [hack book of `Hoa\Stream`](https://central.hoa-project.net/Documentation/Library/Stream) contains