README

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

Hoa\Exception

此库允许使用高级异常。它提供通用异常（通过 hoa://Event/Exception 事件通道发送），空闲异常（不通过事件通道发送），未捕获异常处理器，错误到异常处理器的转换以及异常组（带有事务）。

了解更多信息.

安装

使用 Composer，要将此库包含到依赖中，您需要要求 hoa/exception

$ composer require hoa/exception '~2.0'

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

测试

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

$ composer install

然后，运行所有测试套件

$ vendor/bin/hoa test:run

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

快速使用

我们提供了一般异常的快速概述，如何通过事件监听所有抛出的异常，以及如何使用异常组。

通用异常

异常由以下组成

• 一条消息，
• 一个代码（可选），
• 消息的参数列表（类似于 printf，可选），
• 一个之前的异常（可选）。

因此，以下示例构建了一个异常

$exception = new Hoa\Exception\Exception('Hello %s!', 0, 'world');

异常消息将是：Hello world!。"提升"消息（包含所有信息，而不仅仅是消息）是

{main}: (0) Hello world!
in … at line ….

也显示了之前的异常，例如

$previous  = new Hoa\Exception\Exception('Hello previous.');
$exception = new Hoa\Exception\Exception('Hello %s!', 0, 'world', $previous);

echo $exception->raise(true);

/**
 * Will output:
 *     {main}: (0) Hello world!
 *     in … at line ….
 *     
 *         ⬇
 *     
 *     Nested exception (Hoa\Exception\Exception):
 *     {main}: (0) Hello previous.
 *     in … at line ….
 */

通过事件监听异常

大多数 Hoa 异常都扩展了 Hoa\Exception\Exception，它们在 hoa://Event/Exception 事件通道上自行触发（请参见 Hoa\Event 库）。因此，我们可以通过编写来监听应用程序中抛出的所有异常

Hoa\Event\Event::getEvent('hoa://Event/Exception')->attach(
    function (Hoa\Event\Bucket $bucket) {
        $exception = $bucket->getData();
        // …
    }
);

只有 Hoa\Exception\Idle 异常不会在通道事件上触发。

组和事务

异常组由 Hoa\Exception\Group 表示。一个组是一个包含一个或多个异常的异常。提供了一个事务性 API 来向组中添加更多异常，方法如下

• beginTransaction 用于开始事务，
• rollbackTransaction 用于从 beginTransaction 调用以来删除所有新添加的异常，
• commitTransaction 用于合并之前事务中所有新添加的异常，
• hasUncommittedExceptions 用于检查它们是否是挂起的异常。

例如，如果一个异常行为由多个原因引起，可能会抛出多个异常而不是一个异常。组也可以嵌套，这有助于表示异常树。因此

// A group of exceptions.
$group           = new Hoa\Exception\Group('Failed because of several reasons.');
$group['first']  = new Hoa\Exception\Exception('First reason');
$group['second'] = new Hoa\Exception\Exception('Second reason');

// Can nest another group.
$group['third']           = new Hoa\Exception\Group('Third reason');
$group['third']['fourth'] = new Hoa\Exception\Exception('Fourth reason');

echo $group->raise(true);

/**
 * Will output:
 *     {main}: (0) Failed because of several reasons.
 *     in … at line ….
 *     
 *     Contains the following exceptions:
 *     
 *       • {main}: (0) First reason
 *         in … at line ….
 *     
 *       • {main}: (0) Second reason
 *         in … at line ….
 *     
 *       • {main}: (0) Third reason
 *         in … at line ….
 *         
 *         Contains the following exceptions:
 *         
 *           • {main}: (0) Fourth reason
 *             in … at line ….
 */

以下示例使用事务在组中添加新异常

$group   = new Hoa\Exception\Group('Failed because of several reasons.');
$group[] = new Hoa\Exception\Exception('Always present.');

$group->beginTransaction();

$group[] = new Hoa\Exception\Exception('Might be present.');

if (true === $condition) {
    $group->commitTransaction();
} else {
    $group->rollbackTransaction();
}

文档

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

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

$ 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 了解详细信息。