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中引入了Throwable接口，以表示全新的异常架构。因此，为了与即将到来的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!

Xcallable

Xcallable是“扩展调用者”。它是一个统一的API，用于调用任何类型的调用者，并扩展了Hoa的一些API（如Hoa\Event或Hoa\Stream）。它支持以下类型：

• 'function'作为字符串，
• 'class::method'作为字符串，
• 'class', 'method'作为两个字符串参数，
• $object, 'method'作为两个参数，
• $object, ''作为两个参数，调用者未知，
• 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方法将其参数转换为xcachable。在这种情况下，要调用的方法未知，我们只有一个对象（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以获取详细信息。