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!。"raise" 消息（包含所有信息，而不仅仅是消息）是

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