README

Warbsorber（《警告吸收器》）

问题

许多内置PHP函数在失败时会产生警告消息。这种做法非常糟糕 - 直接输出到输出，只能在安装了特殊的错误处理程序时捕获。

当然，现代（正确）的传递失败细节的方法是使用 异常，但由于遗留原因，许多旧的内置函数无法这样做，并且可能永远无法“修复”。

解决方案

此库为执行任意 代码块 提供了一个包装器，该代码块可能会发出警告、通知或错误。

所有这些消息都被包装器“吸收”，并在执行 代码块 后以良好的方式返回，以便稍后检查。

要求

需要

• PHP >= 8.0

安装

使用composer安装

composer require margusk/warbsorber

使用

use function margusk\Warbsorber;

$fopenWarnings = Warbsorber(function () use (&$fp) {
    $fp = fopen("php://non-existent-stream", "r");
});

if (!$fp) {
    echo "fopen() failed with messages: \n";

    foreach ($fopenWarnings as $entry) {
        echo "- " . $entry->errStr . "\n";
    }
}

输出

fopen() failed with messages:
- fopen(): Invalid php:// URL specified
- fopen(php://non-existent-stream): Failed to open stream: operation failed

上面的代码显示了如何调用fopen，它注定要失败。我们不仅得到了返回值 false，而且还捕获了调用失败的原因文本。这些原因可以稍后呈现给最终用户进行修复。

从消息中移除函数名称

如果我们想将所有消息合并成一个段落，我们已经知道这些消息与 fopen() 相关，所以消息开头（fopen()：和fopen(php://non-existent-stream)：）实际上是无关紧要的，是过多的信息。

让我们通过使用 removeFunctionPrefix(string $funcName) 方法来消除它们

use function margusk\Warbsorber;

$fopenWarnings = Warbsorber(function () use (&$fp) {
    $fp = fopen("php://non-existent-stream", "r");
});

if (!$fp) {
    $fopenWarnings = $fopenWarnings->removeFunctionPrefix('fopen');

    echo "fopen() failed with: "
        .implode(
            '. ',
            array_map(
                fn(Entry $e) => $e->errStr,
                $fopenWarnings->getArrayCopy()
            )
        )
        .".\n";
}

现在输出变得更干净了

fopen() failed with: Invalid php:// URL specified. Failed to open stream: operation failed.

注意，$fopenWarnings 是不可变对象，这使得 removeFunctionPrefix 返回修改后的数据的克隆实例。

仅捕获特定错误级别的消息

默认情况下，在执行代码块期间会捕获所有消息，无论级别如何（例如 E_WARNING、E_NOTICE 等）。但是，如果需要，可以通过在 Warbsorber 调用中添加第二个参数来更改此设置。

use function margusk\Warbsorber;

$fopenWarnings = Warbsorber(function () use (&$fp) {
    $fp = fopen("php://non-existent-stream", "r");
}, E_WARNING | E_NOTICE | E_DEPRECATED);

这只捕获级别为 E_WARNING、E_NOTICE 或 E_DEPRECATED 的消息

文档

主要包装器 Warbsorber(\Closure $callback, int $level = E_ALL): Warnings; 返回 margusk\Warbsorber\Warnings 的实例

类 margusk\Warbsorber\Warnings

• 实现 IteratorAggregate、Countable 和 ArrayAccess
• 每个条目都是 margusk\Warbsorber\Entry 的实例
• 方法 getArrayCopy(): array 返回原始数组中的消息
• 方法 removeFunctionPrefix(string $funcName): static 从消息开头删除指定的函数名称，并返回其自身的克隆实例

类 margusk\Warbsorber\Entry

• 保存单个消息的数据
  • $entry->errNo 获取错误级别
  • $entry->errStr 获取错误消息
  • $entry->errFile 获取触发错误的文件
  • $entry->errLine 获取触发错误的行

许可证

此库在MIT许可证下发布。