README

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

Hoa\Consistency

此库提供了一个薄层，位于 PHP 虚拟机和库之间，以确保跨虚拟机版本和库版本的兼容性。

了解更多.

安装

使用 Composer，要将此库添加到依赖项中，您需要要求 hoa/consistency

$ composer require hoa/consistency '~2.0'

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

测试

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

$ composer install

然后，运行所有测试套件

$ vendor/bin/hoa test:run

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

快速使用

我们提出了一个关于一致性 API 如何确保前向和后向兼容性的快速概述，以及 PSR-4 自动加载器和 xcallable API 的概述。

前向和后向兼容性

Hoa\Consistency\Consistency 类确保前向和后向兼容性。

带有关键字的示例

Hoa\Consistency\Consistency::isKeyword 检查特定单词是否被 PHP 保留。假设您的当前 PHP 版本不支持 callable 关键字或如 int、float、string 等类型声明，则 isKeyword 方法将告诉您它们是否为保留关键字：这不仅适用于您的当前 PHP 版本，还可能适用于即将推出的版本。

$isKeyword = Hoa\Consistency\Consistency::isKeyword('yield');

这避免了编写可能在将来或针对使用前沿技术的用户中中断的程序。

带有关键字的示例

PHP 标识符由正则表达式定义。这可能在将来发生变化。为了防止破坏您的算法，您可以使用 Hoa\Consistency\Consistency::isIdentifier 方法来检查标识符是否根据当前 PHP 版本正确

$isValidIdentifier = Hoa\Consistency\Consistency::isIdentifier('foo');

灵活实体

灵活实体非常简单。如果我们声明 Foo\Bar\Bar 为灵活实体，我们将能够使用 Foo\Bar\Bar 名称或 Foo\Bar 访问它。这在您的架构演变但希望保持向后兼容性时非常有用。例如，您通常会创建一个位于 Foo/Bar/Exception.php 文件中的 Foo\Bar\Exception 类。但是，在几个版本之后，您可能会意识到需要引入其他异常，因此需要一个 Exception 目录。在这种情况下，Foo\Bar\Exception 应移动到 Foo\Bar\Exception\Exception。如果后者被声明为灵活实体，则可以保持向后兼容性。

Hoa\Consistency\Consistency::flexEntity('Foo\Bar\Exception\Exception');

另一个示例是“入口类”（非正式命名）。Hoa\Consistency\Consistency 是一个很好的例子。使用 Hoa\Consistency 而不是 Hoa\Consistency\Consistency 更方便。这是因为这是一个灵活实体。

可抛出异常及其相关内容

Throwable 接口已被引入以表示 PHP 中全新的异常架构。因此，为了与即将推出的 PHP 版本兼容，您可能希望在某些情况下使用此接口。希望如果不存在，将为您创建 Throwable 接口。

try {
    …
} catch (Throwable $e) {
    …
}

自动加载器

Hoa\Consistency\Autoloader 是一个与 PSR-4 兼容 的自动加载器。它的工作方式如下

• addNamespace 用于将命名空间前缀映射到目录
• register 用于注册自动加载器

API 还提供了 load 方法来强制加载实体，unregister 来注销自动加载器，getRegisteredAutoloaders 来获取所有已注册的自动加载器列表等。

例如，将 Foo\Bar 命名空间映射到 Source/ 目录

$autoloader = new Hoa\Consistency\Autoloader();
$autoloader->addNamespace('Foo\Bar', 'Source');
$autoloader->register();

$baz = new Foo\Bar\Baz(); // automatically loaded!

可调用的扩展

可调用的扩展是“扩展可调用的”。它是一个统一的 API，用于调用任何类型的可调用对象，并扩展了一些 Hoa 的 API（如 Hoa\Event 或 Hoa\Stream）。它理解以下几种类型

• 'function' 作为字符串
• 'class::method' 作为字符串
• 'class', 'method' 作为两个字符串参数
• $object, 'method' 作为两个参数
• $object, '' 作为两个参数，"able" 未知
• function (…) { … } 作为闭包
• ['class', 'method'] 作为字符串数组
• [$object, 'method'] 作为数组

要使用它，只需实例化 Hoa\Consistency\Xcallable 类并将其用作函数

$xcallable = new Hoa\Consistency\Xcallable('strtoupper');
var_dump($xcallable('foo'));

/**
 * Will output:
 *     string(3) "FOO"
 */

Hoa\Consistency\Xcallable::distributeArguments 方法调用可调用对象，但参数作为数组传递

$xcallable->distributeArguments(['foo']);

也可以获取可调用对象的唯一哈希值

var_dump($xcallable->getHash());

/**
 * Will output:
 *     string(19) "function#strtoupper"
 */

最后，可以获取当前可调用对象的反射实例（可以是 ReflectionFunction、ReflectionClass、ReflectionMethod 或 ReflectionObject）

var_dump($xcallable->getReflection());

/**
 * Will output:
 *     object(ReflectionFunction)#42 (1) {
 *       ["name"]=>
 *       string(10) "strtoupper"
 *     }
 */

当对象已设置但方法未设置时，如果可能，将推断方法。如果对象是 Hoa\Stream 类型，则根据传递给可调用的参数类型，将使用 writeInteger、writeString、writeArray 等方法。如果参数是 Hoa\Event\Bucket 类型，则将根据事件桶中的数据进行方法名推断。这非常方便。例如，以下示例将无缝工作

Hoa\Event\Event::getEvent('hoa://Event/Exception')
    ->attach(new Hoa\File\Write('Exceptions.log'));

Hoa\Event\Event 上的 attach 方法将其参数转换为 xcallable。在这种情况下，要调用的方法未知，我们只有一个对象（Hoa\File\Write 类型）。然而，因为这是一个流，所以将根据在 hoa://Event/Exception 事件通道上触发的事件桶中的数据进行方法推断。

文档

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

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

$ 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获取详细信息。