README

Hoa 是一套 模块化、可扩展 和 结构化 的 PHP 库。
此外，Hoa 致力于成为工业界和学术界之间的桥梁。

Hoa\Stream

这个库在 PHP 流之上提供了一层高级抽象。它包括

• 流操作：打开、关闭、自动关闭、超时、阻塞模式、缓冲区大小、元数据等
• 流通知：根据流包装器，支持的监听器包括以下几种：authrequire、authresult、complete、connect、failure、mimetype、progress、redirect、resolve 和 size
• 上下文：允许向流包装器传递选项和参数，例如 HTTP 头
• 过滤器：一个位于流源和目的地之间的函数，例如用于加密/解密数据或进行更高级的操作（如仪表化）
• 包装器：声明用户定义的协议，这些协议将被 PHP 标准库自然处理（如 fopen、stream_get_contents 等）
• 接口：每个接口代表流可以提供的能力

这个库是其他几个库的基础，例如 Hoa\File 或 Hoa\Socket（以及 Hoa\Websocket）。

了解更多.

安装

使用 Composer，要将此库包含到依赖项中，您需要添加 hoa/stream

$ composer require hoa/stream '~1.0'

有关更多安装说明，请参阅源代码页面。

测试

在运行测试套件之前，必须安装开发依赖项

$ composer install

然后，要运行所有测试套件

$ vendor/bin/hoa test:run

有关更多信息，请参阅贡献指南。

快速使用

为了快速概述，我们建议您了解 Hoa\Stream 提供的接口，即流能力。这是此库最重要的部分之一。然后，如何定义流，接着是使用流上下文。事件、监听器和通知将在下一节中详细介绍。最后，包装器和过滤器将在最后几节中详细说明。

接口，即流能力

此库定义了几个接口，代表重要的流能力。这在设计用于处理流的函数或库时非常有用。它确保流是分型的并提供了某些功能。接口声明在 Hoa\Stream\IStream 命名空间中

• In，从流中读取，提供 read、readInteger、readLine、readAll、eof 等
• Out，向流写入，提供 write、writeArray、writeLine、truncate 等
• Bufferable，对于至少有一个内部缓冲区的流，提供 newBuffer、flush、getBufferLevel 等
• Touchable，对于“可触摸”的流，提供 touch、copy、move、delete、changeGroup 等
• Lockable，用于锁定流，提供了lock和表示不同类型锁的几个常量，如LOCK_SHARED、LOCK_EXCLUSIVE、LOCK_NO_BLOCK等。
• Pathable，针对基于路径的流，提供了getBasename和getDirname。
• Pointable，用于移动流内部指针（如果有的话），提供了rewind、seek和tell。
• Statable，用于获取有关流的统计信息，提供了getSize、getStatistics、getATime、getCTime、isReadable等。
• Structural，针对结构化流，即像树一样操作的流，提供了selectRoot、selectAnyElements、selectElements、selectAdjacentSiblingElement、querySelector等。

因此，如果只需要从流中读取，它将以Hoa\Stream\IStream\In类型指定流。这也允许实现者选择其流将提供或不提供哪些功能。

最后，最高级别的接口是Stream，定义了getStream方法，仅此而已。这是最不确定的流。所有功能都必须扩展此接口。

定义一个具体的流

主要的Hoa\Stream\Stream类是抽象的。留下了两个方法实现供用户使用：_open和_close，分别用于打开特定的流和关闭此特定的流，例如

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());
    }
}

然后，最常用的用法将是

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

这就完了。这个流还没有能力。让我们实现In能力

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

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

    // …
}

其他方法留给读者作为练习。因此，我们现在能够

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

Stream能力已经由Hoa\Stream\Stream类实现。

上下文流

上下文由Hoa\Stream\Context类表示。它代表了一组流选项和参数。例如，请参见http://流的选项和参数。多亏了上下文，可以添加HTTP头信息，或指定代理、最大重定向次数等。所有这些信息都是流的选项/参数。

要使用它们，首先让我们定义上下文

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

然后，我们可以根据选择的上下文ID请求流使用此上下文，如下所示

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

对于流实现者，Hoa\Stream\Context类上的getOptions和getParameters方法将非常有用，分别用于检索选项和参数，并根据它们执行操作。

“选项”和“参数”的概念由PHP本身定义。

事件、监听器和通知

流有一些事件和几个监听器。到目前为止，监听器大多代表“流通知”。

注册了两个事件：hoa://Event/Stream/<streamName>和hoa://Event/Stream/<streamName>:close-before。例如，要在一个流关闭前执行函数，可以写

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

记住，流不一定是文件。它可以是套接字、WebSocket、stringbuffer、你定义的任何流……因此，这个事件可以在非常不同的场景中使用，比如记录日志、关闭相关资源、触发另一个事件……没有规则。观察到的流仍然打开，理论上还可以使用。

当调用Hoa\Stream\Stream::close方法时，将触发此事件。

现在让我们谈谈监听器。要注册监听器，我们必须创建我们的流的一个实例，但不打开它。这个动作称为“延迟打开”。我们可以通过默认Hoa\Stream\Stream构造函数的第三个参数控制打开时间；设置为true以延迟打开，如下所示

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

将null作为第二个参数传递表示：无上下文。请注意，我们必须手动调用open方法来打开流。在流实例化和流打开之间，我们可以附加新的监听器。

根据流的实现方式，将触发不同的监听器。术语“监听器”在Hoa中到处使用，但在PHP的流上下文中，它们被称为通知。以下是一个使用HTTP流的示例

$basic = new BasicFile(
    'https://hoa-project.net/', // stream name
    null,                       // context ID
    true                        // defere opening
);
$basic->on(
    'connect',
    function (Hoa\Event\Bucket $bucket) {
        echo 'Connected', "\n";
    }
);
$basic->on(
    'redirect',
    function (Hoa\Event\Bucket $bucket) {
        echo 'Redirection to ', $bucket->getData()['message'], "\n";
    }
);
$basic->on(
    'mimetype',
    function (Hoa\Event\Bucket $bucket) {
        echo 'MIME-Type is ', $bucket->getData()['message'], "\n";
    }
);
$basic->on(
    'size',
    function (Hoa\Event\Bucket $bucket) {
        echo 'Size is ', $bucket->getData()['max'], "\n";
    }
);
$basic->on(
    'progress',
    function (Hoa\Event\Bucket $bucket) {
        echo 'Progressed, ', $bucket->getData()['transferred'], ' bytes downloaded', "\n";
    }
);

// Then open.
$basic->open();

您可能会看到以下内容

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

监听器的完整列表如下

• authrequire，当需要认证时，
• authresult，当认证结果已知时，
• complete，当流完成时（这意味着可能有很多变化），
• connect，当流连接时（这意味着可能有很多变化），
• failure，当发生意外情况时，
• mimetype，当流的MIME类型已知时，
• progress，当有显著进展时，
• redirect，当流被重定向到另一个流时，
• resolve，当流被解析时（这意味着可能有很多变化），
• size，当流的尺寸已知时。

所有监听器桶数据都是一个包含以下对的数组

• code，STREAM_NOTIFY_*常量之一，这基本上是监听器名称（请参阅文档），
• severity，STREAM_NOTIFY_SEVERITY_*常量之一
  • STREAM_NOTIFY_SEVERITY_INFO，正常，非错误相关的通知，
  • STREAM_NOTIFY_SEVERITY_WARN，非关键错误条件，处理可以继续，
  • STREAM_NOTIFY_SEVERITY_ERR，发生了关键错误，处理无法继续。
• message，包含最有用信息的字符串，
• transferred，已传输的字节数，
• max，要传输的总字节数。

流实现者可以添加更多监听器。请参阅Hoa\Event库。并非所有监听器都会由所有类型的流触发。

包装器

流包装器允许声明方案，如hoa://或fortune://。您可以想象添加您最喜欢的在线存储，cloud://。任何流包装器都可以与原生标准PHP函数一起使用，如fopen、file_get_contents、mkdir、touch等。对用户来说将是透明的。

Hoa\Stream\Wrapper\Wrapper类包含所有用于register、unregister和restore包装器的方法。isRegistered和getRegistered方法也很有帮助。包装器由一个类表示

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

包装器必须实现Hoa\Stream\Wrapper\IWrapper\IWrapper接口。它是同一命名空间中两个其他接口的组合：Stream和File。

Stream接口需要实现与流相关的方法，如下所示

• stream_open,
• stream_close,
• stream_cast,
• stream_eof,
• stream_flush,
• stream_lock,
• stream_metadata,
• stream_read,
• stream_write,
• stream_seek,
• stream_tell,
• stream_stat,
• 等等。

API提供了所有所需的信息。

File接口需要实现与流作为文件操作相关的其他方法，如下所示

• mkdir,
• dir_opendir,
• dir_closedir,
• dir_readdir,
• rename,
• unlink,
• 等等。

实现示例是Hoa\Protocol库中的hoa://方案。它不依赖于此库以避免依赖关系，但代码可能很有帮助。

过滤器

流就像一个管道，有输入和输出。可以截断这个管道成两部分，并插入一小部分：一个过滤器。有三种类型的过滤器，由 Hoa\Stream\Filter\Filter 类上的常量来标识

1. Filter::READ 当过滤器应用于读取操作时
2. Filter::WRITE 当过滤器应用于写入操作时
3. Filter::READ_AND_WRITE 当两者都应用时

该类允许通过 register 或 remove 方法注册或删除过滤器。过滤器采用扩展 Hoa\Stream\Filter\Basic 过滤器的类的形式，以及一个相关联的名称。这不是强制的，但强烈推荐。

一旦注册了过滤器，我们就可以通过使用其名称，通过 append 或 prepend 方法将其应用于流。你可能已经猜到了，可以在流上应用多个过滤器，按特定顺序，例如“解密”、“解压”、“转换为...”。在这种情况下，顺序很重要。

最后，我们像往常一样使用流。流不一定是 Hoa\Stream 的实例，它可以是任何 PHP 流资源。传递一个 Hoa\Stream 实例将显然展开为其底层 PHP 流资源。

让我们实现一个过滤器，该过滤器将流的内容转换为大写。我们首先定义我们的过滤器

class ToUpper extends Hoa\Stream\Filter\Basic
{
    public function filter($in, $out, &$consumed, $closing)
    {
        $iBucket = new Hoa\Stream\Bucket($in);
        $oBucket = new Hoa\Stream\Bucket($out);

        while (false === $iBucket->eob()) {
            $consumed += $iBucket->getLength();

            $iBucket->setData(strtoupper($iBucket->getData()));
            $oBucket->append($iBucket);
        }

        unset($iBucket);
        unset($oBucket);

        return parent::PASS_ON;
    }
}

太好了。现在让我们注册我们的过滤器以特定的名称

$filterName = 'toupper';
Hoa\Stream\Filter::register($filterName, ToUpper::class);

然后，我们必须在特定的流上应用该过滤器，所以让我们打开一个流，并附加过滤器

$file = new Hoa\File\Read(__FILE__);
Hoa\Stream\Filter::append($file, $filterName, Hoa\Stream\Filter::READ);

这个过滤器仅应用于读取操作。因此，当我们在流上读取时，我们将看到其效果，让我们试试

echo $file->readAll();

你将看到所有内容都是 ASCII 大写。

过滤器是一个低级流 API。它与各种流集成。这是一个非常强大的工具。我们提到了一些用法，如解密、转换、解压等。实际上，PHP 随带一些标准过滤器，如：string.toupper、string.tolower、dechunk、zlib.*、bzip2.*、convert.iconv.* 等。使用 Hoa\Stream\Filter\Filter::getRegistered 方法将提供所有已注册过滤器的列表。

Hoa\Stream\Filter\LateComputed 类是一个特殊的过滤器。它在流到达其末尾时调用其公共 compute 方法。因此，通过扩展此过滤器，您可以重写 compute 方法并工作于 _buffer 属性。此缓冲区包含流的全部内容。这是一个真正的缓冲区。为什么它会有用？例如，如果您正在读取 PHP 文件，您可以使用解析器（例如）即时转换源代码，并重写文件的一部分。这项技术特别有助于对代码进行仪器化（添加一些探头）。

这也可能通过包装器自动应用一个过滤器！例如，instrument:// 包装器可以在 stream_open 方法（从 Hoa\Stream\Wrapper\IWrapper\Stream 接口）中打开流时预先附加一个过滤器。

可能性是无数的。

其他操作

还有更多要介绍。 Hoa\Stream 支持复合流（使用 Hoa\Stream\Composite 抽象类），即嵌入其他流的流，例如 的 Hoa\Xml 库。一个 XML 流从另一个内部流（文件、套接字或任何其他内容）读取和写入。 的 Hoa\Stringbuffer 库 允许使用流 API 处理字符串，因此流内容将写入磁盘。流功能与 Hoa\File 不同，正如你可能猜到的。

文档

Hoa\Stream 的黑客书 包含有关如何使用此库及其工作原理的详细信息。

要本地生成文档，请执行以下命令

$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open

有关更多文档，请访问项目的网站：hoa-project.net。

获取帮助

主要有两种获取帮助的方法

• 在 #hoaproject IRC 频道中，
• 在 users.hoa-project.net 论坛上。

贡献

您想要贡献力量吗？谢谢！一份详细的贡献指南解释了您需要了解的所有内容。

许可协议

Hoa 采用新的 BSD 许可协议（BSD-3-Clause）。请参阅LICENSE以获取详细信息。

相关项目

以下项目正在使用这个库

• Marvirc，一个简单、极其模块化和速度极快的 IRC 机器人，
• WellCommerce，基于 Symfony 3 全栈框架的现代电子商务引擎，
• 当然还有许多 Hoa 的库。