百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
S

Stream

> 编程语言
开源

Hoa\Stream 库。

313 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

Hoa\Stream 库。


Hoa is a modular, extensible and structured set of PHP libraries.

Moreover, Hoa aims at being a bridge between industrial and research worlds.

Hoa\Stream

This library is a high-level abstraction over PHP streams. It includes:

  • Stream manipulations: Open, close, auto-close, timeout, blocking mode, buffer size, metadata etc.,
  • Stream notifications: Depending of the stream wrapper, the supported listeners are the following: authrequire, authresult, complete, connect, failure, mimetype, progress, redirect, resolve, and size,
  • Context: Allow to pass options and parameters to the stream wrappers, for instance HTTP headers,
  • Filter: A function that sits between the source and the destination of a stream, useful for instance to encrypt/decrypt a data on-the-fly, or for more advanced tricks like instrumentation,
  • Wrapper: Declare user-defined protocols that will naturally be handled by the PHP standard library (like fopen, stream_get_contents etc.),
  • Interfaces: One interface per capability a stream can offer.

This library is the foundation of several others, e.g. Hoa\File or Hoa\Socket (and so Hoa\Websocket).

Learn more.

Installation

With Composer, to include this library into your dependencies, you need to require hoa/stream:

bash
$ composer require hoa/stream '~1.0'

For more installation procedures, please read the Source page.

Testing

Before running the test suites, the development dependencies must be installed:

bash
$ composer install

Then, to run all the test suites:

bash
$ vendor/bin/hoa test:run

For more information, please read the contributor guide.

Quick usage

As a quick overview, we propose to discover what Hoa\Stream provides in term of interfaces, i.e. stream capabilities. This is almost the most important part of this library. Then, how to define a stream, followed by how to use stream contexts. Events, listeners and notifications will be detailed in the next section. Finally, wrappers and filters are detailed in the last sections.

Interfaces, aka stream capabilities

This library defines several interfaces representing important stream capabilities. This is very useful when designing a function, or a library, working with streams. It ensures the stream is typed and offers certain capabilities. The interfaces are declared in the Hoa\Stream\IStream namespace:

  • In, to read from a stream, provides read, readInteger, readLine, readAll, eof etc.,
  • Out, to write onto a stream, provides write, writeArray, writeLine, truncate etc.,
  • Bufferable, for streams with at least one internal buffer, provides newBuffer, flush, getBufferLevel etc.,
  • Touchable, for “touchable” streams, provides touch, copy, move, delete, changeGroup etc.,
  • Lockable, to lock a stream, provides lock and several constants representing different kind of locks, like LOCK_SHARED, LOCK_EXCLUSIVE, LOCK_NO_BLOCK etc.,
  • Pathable, for path-based stream, provides getBasename and getDirname,
  • Pointable, to move the internal pointer of the stream if any, provides rewind, seek and tell,
  • Statable, to get statistics about a stream, provides getSize, getStatistics, getATime, getCTime, isReadable etc.,
  • Structural, for a structural stream, i.e. a stream acting like a tree, provides selectRoot, selectAnyElements, selectElements, selectAdjacentSiblingElement, querySelector etc.

Thus, if one only need to read from a stream, it will type the stream with Hoa\Stream\IStream\In. It also allows an implementer to choose what capabilities its stream will provide or not.

Finally, the highest interface is Stream, defining the getStream method, that's all. That's the most undefined stream. All capabilities must extend this interface.

Define a concrete stream

The main Hoa\Stream\Stream class is abstract. Two method implementations are left to the user: _open and : _close, respectively to open a particular stream, and to close this particular stream, for instance:

php
class BasicFile extends Hoa\Stream\Stream
{
    protected function &_open($streamName, Hoa\Stream\Context $context = null)
    {
        if (null === $context) {
            $out = fopen($streamName, 'rb');
        } else {
            $out = fopen($streamName, 'rb', false, $context->getContext());
        }

        return $out;
    }

    protected function _close()
    {
        return fclose($this->getStream());
    }
}

Then, the most common usage will be:

php
$file = new BasicFile('/path/to/file');

That's all. This stream has no capability yet. Let's implement the In capability:

php
class BasicFile extends Hoa\Stream\Stream implements Hoa\Stream\IStream\In
{
    // …

    public function read($length)
    {
        return fread($this->getStream(), max(1, $length));
    }

    // …
}

Other methods are left as an exercise to the reader. Thus, we are now able to:

php
$chunk = $file->read(42);

The Stream capability is already implemented by the Hoa\Stream\Stream class.

Contextual streams

A context is represented by the Hoa\Stream\Context class. It represents a set of options and parameters for the stream. See the options and parameters for the http:// stream wrapper as an example of possible ones. Thanks to context, this is possible to add HTTP headers for instance, or to specify the proxy, the maximum number of redirections etc. All these information are options/parameters of the stream.

To use them, first let's define the context:

php
$contextId = 'my_http_context';
$context   = Hoa\Stream\Context::getInstance($contextId);
$context->setOptions([
    // …
]);

And thus, we can ask a stream to use this context based on the chosen context ID, like this:

php
$basicFile = new BasicFile('/path/to/file', $contextId);

For the stream implementer, the getOptions and getParameters methods on the Hoa\Stream\Context class will be useful to respectively retrieve the options and the parameters, and acts according to them.

The concept of options and parameters are defined by PHP itself.

Events, listeners, and notifications

A stream has some events, and several listeners. So far, listeners mostly represent “stream notifications”.

2 events are registered: hoa://Event/Stream/ and hoa://Event/Stream/:close-before. Thus, for instance, to execute a function before the /path/to/file stream closes, one will write:

php
Hoa\Event\Event::getEvent('hoa://Event/Stream//path/to/file:close-before')->attach(
    function (Hoa\Event\Bucket $bucket) {
        // do something!
    }
);

Remember that a stream is not necessarily a file. It can be a socket, a WebSocket, a stringbuffer, any stream you have defined… Consequently, this event can be used in very different manner for various scenario, like logging things, closing related resources, firing another event… There is no rule. The observed stream is still opened, and can theoritically still be used.

This event is fired when calling the Hoa\Stream\Stream::close method.

Now let's move on to listeners. To register a listener, we must create an instance of our stream without opening it. This action is called “deferred opening”. We can control the opening time with the third argument of the default Hoa\Stream\Stream constructor; true to defer the opening, like:

php
$file = new BasicFile('/path/to/file', null, true);
// do something
$file->open();

Passing null as a second argument means: No context. Note that we must manually call the open method to open the stream then. Between the stream instanciation and the stream opening, we can attach new listeners.

Depending of the stream implementation, different listeners will be fired. The term “listener” is the one used everywhere in Hoa, but PHP —in the context of stream— refers to them as notifications. Let's take an example with an HTTP stream:

…

You might see something like this:

Connected
MIME-Type is text/html; charset=UTF-8
Redirection to /En/
Connected
MIME-Type is text/html; charset=UTF-8
Progressed, … bytes downloaded
Progressed, … bytes downloaded

The exhaustive list of listeners is the following:

  • authrequire, when the authentication is required,
  • authresult, when the result of the authentication is known,
  • complete, when the stream is complete (meaning can vary a lot here),
  • connect, when the stream is connected (meaning can vary a lot here),
  • failure, when something unexpected occured,
  • mimetype, when the MIME-type of the stream is known,
  • progress, when there is significant progression,
  • redirect, when the stream is redirected to another stream,
  • resolve, when the stream is resolved (meaning can vary a lot here),
  • size, when the size of the stream is known.

All listener bucket data is an array containing the following pairs:

  • code, one of the STREAM_NOTIFY_* constant, which is basically the listener name (see the documentation),
  • severity, one of the STREAM_NOTIFY_SEVERITY_* constant:
    • STREAM_NOTIFY_SEVERITY_INFO, normal, non-error related, notification,
    • STREAM_NOTIFY_SEVERITY_WARN, non critical error condition, processing may continue,
    • STREAM_NOTIFY_SEVERITY_ERR, a critical error occurred, processing cannot continue.
  • message, a string containing most useful information,
  • transferred, amount of bytes already transferred,
  • max, total number of bytes to transfer.

This is possible for the stream implementer to add more listeners. Please, take a look at the Hoa\Event library. Not all listeners will be fired by all kind of streams.

Wrappers

A stream wrapper allows to declare schemes, like hoa:// or fortune://. You can imagine adding your favorite online storage too, cloud://. Any stream wrapper can be used with native standard PHP functions, like fopen, file_get_contents, mkdir, touch etc. It will be transparent for the user.

The Hoa\Stream\Wrapper\Wrapper class holds all methods to register, unregister, and restore wrappers. The isRegistered and getRegistered methods are also helpful. A wrapper is represented by a class:

php
Hoa\Stream\Wrapper\Wrapper::register('tmp', Tmp::class);

A wrapper must implement the Hoa\Stream\Wrapper\IWrapper\IWrapper interface. It is a combination of two other interfaces in the same namespace: Stream and File.

The Stream interface requires to implement several methods related to a stream, such as:

  • stream_open,
  • stream_close,
  • stream_cast,
  • stream_eof,
  • stream_flush,
  • stream_lock,
  • stream_metadata,
  • stream_read,
  • stream_write,
  • stream_seek,
  • stream_tell,
  • stream_stat,
  • etc.

The API provides all required information.

The File interface requires to implement other methods related to stream acting as a file, such as:

  • mkdir,
  • dir_opendir,
  • dir_closedir,
  • dir_readdir,
  • rename,
  • unlink,
  • etc.

An example of an implementation is the hoa:// scheme in the Hoa\Protocol library. It does not depend on this library to avoi

Issues· 5 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

PHPhoalibraryphpstream

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言