README

PHP的嵌入式异常错误处理。

安装和文档

• 作为Composer包eloquent/asplode提供。
• 可用的API文档。

用法

通过单个语句即可安装Asplode错误处理器

Eloquent\Asplode\Asplode::install();

Asplode做什么？

Asplode是一个非常简单的PHP错误处理器实现，它抛出ErrorException异常，而不是使用默认的PHP错误处理行为。这意味着所有非致命的运行时错误都以异常的形式呈现给开发者。这也意味着任何未处理的错误都交付给单个点：全局异常处理器。

为什么使用Asplode？

开发者需要决定当错误发生时他们的代码如何行为。异常提供了在PHP中报告和恢复错误的唯一真正一致的方式。

这种处理错误的方法已被证明非常有效。类似的策略在Laravel等主要PHP框架中使用。Asplode是一个独立的实现，可用于任何项目。

致命错误处理

虽然无法从致命PHP错误中恢复，但可以以与未捕获异常相同的方式报告致命错误。

在Asplode中，致命错误会导致传递给全局异常处理器的表示致命错误的合成异常。这允许开发者在PHP解释器关闭之前优雅地通知用户致命错误。

默认情况下安装了Asplode的致命错误处理器，但只有在安装了全局异常处理器时才会激活。

set_exception_handler(
    function (Exception $e) {
        echo $e->getMessage();
    }
);

Eloquent\Asplode\Asplode::install();

要使用不带致命错误处理器的Asplode，请使用Asplode::installErrorHandler()而不是Asplode::install()。要仅使用致命错误处理器，请使用Asplode::installFatalHandler()。

请注意，在PHP关闭阶段尝试自动加载文件可能会出现问题；因此，自定义异常处理器应尽可能显式加载其依赖项。

断言当前错误处理器兼容性

假设使用Asplode的代码可能不会按预期工作，除非安装了正确的错误处理器类型。例如，如果安装的错误处理器不抛出ErrorException实例，则期望在失败时捕获ErrorException的代码将会有不可预测的结果。

为了确保安装了正确配置的错误处理器，Asplode提供了Asplode::assertCompatibleHandler()方法。

use Eloquent\Asplode\Asplode;
use Eloquent\Asplode\Exception\ErrorHandlingConfigurationException;

try {
    Asplode::assertCompatibleHandler();
} catch (ErrorHandlingConfigurationException $e) {
    // handle appropriately
}

兼容的错误处理器是指任何抛出 ErrorException 异常的处理器。它不需要是 Asplode 提供的实现。

管理 PHP 的处理器堆栈

PHP 的错误和异常处理器类似于 堆栈 的行为。然而，操作堆栈的接口有限，并且坦白地说，实现得不好。

Asplode 包含了两个类来帮助管理这些堆栈，即 ErrorHandlerStack 和 ExceptionHandlerStack。这两个类都实现了 HandlerStackInterface，它提供了一个熟悉的工作与堆栈的接口。这些类不需要使用 Asplode 处理器；它们可以作为独立的方式用来管理处理器堆栈。

将现有代码迁移到与 Asplode 一起工作

当安装 Asplode 错误处理器时，error_reporting 设置将不再有任何效果。通知、警告和错误都将导致抛出异常。弃用通知不会抛出异常，但如果没有配置 PHP，仍然会被记录。

已经编写来处理旧式 PHP 错误的代码很可能需要重写。例如，这种类型的逻辑

$fp = fopen('/path/to/foo', 'r'); // this throws a PHP warning if the file is not found

if ($fp === false) {
  // handle error opening file
}

需要重写以处理异常

try {
  $fp = fopen('/path/to/foo', 'r');
} catch (ErrorException $e) {
  // handle error opening file
}

重要的是要注意，PHP 在报告错误条件方面可能非常不一致。一些函数将返回布尔值 false 来指示已发生错误；其他函数可能需要开发者调用额外的函数来检查错误；还有一些函数可能表现出完全非标准的行为。

Asplode 并没有免除开发者阅读 PHP 文档或确保他们考虑了所有可能的错误条件的责任。

执行旧代码

有时与使用不良习惯的代码一起工作是不可避免的。一个旧版 PHP 库可能完全功能性和有用，但它可能没有预料到在发生错误时抛出异常。

Asplode 的异常和错误处理器堆栈都实现了 executeWith() 方法，允许使用与当前安装的处理器不同的处理器执行代码。此方法临时从堆栈中移除所有当前处理器，安装指定的处理器（如果提供），然后执行提供的回调。在回调执行后，将恢复原始处理器。

use Eloquent\Asplode\HandlerStack\ErrorHandlerStack;

$stack = new ErrorHandlerStack;

$result = $stack->executeWith(
    function () {
        // this code will be executed under the default handler
    }
);

$result = $stack->executeWith(
    function () {
        // this code will be executed under the supplied handler
    },
    'errorHandlerFunctionName'
);

$result = $stack->executeWith(
    function () {
        // this code will be executed under the supplied handler
    },
    function ($severity, $message, $path, $lineNumber) {
        // handle the error
    }
);