README

PHPBrake

特性

PHPBrake是官方的Airbrake PHP错误通知器。PHPBrake支持PHP 8.2及以上版本。PHPBrake包含许多有用的功能，让您可以控制何时以及向Airbrake发送什么信息，您可以

• 从代码中的try-catch块发送通知
• 向通知添加自定义数据
• 从通知中过滤敏感数据
• 忽略特定异常
• 配置错误处理器以捕获未捕获的异常
• 与monolog集成
• 与Laravel集成
• 与CakePHP 3.x集成
• 与Symfony集成
• 与Zend集成
• 等等

安装

composer require airbrake/phpbrake

快速入门

// Create new Notifier instance.
$notifier = new Airbrake\Notifier([
    'projectId' => 12345, // FIX ME
    'projectKey' => 'abcdefg' // FIX ME
]);

// Set global notifier instance.
Airbrake\Instance::set($notifier);

// Register error and exception handlers.
$handler = new Airbrake\ErrorHandler($notifier);
$handler->register();

// Somewhere in the app...
try {
    throw new Exception('hello from phpbrake');
} catch(Exception $e) {
    Airbrake\Instance::notify($e);
}

API

通知器API包括4个方法

• buildNotice - 构建Airbrake通知。
• sendNotice - 向Airbrake发送通知。
• notify - buildNotice和sendNotice的快捷方式。
• addFilter - 添加可以修改和/或过滤通知的过滤器。

向通知添加自定义数据

$notifier->addFilter(function ($notice) {
    $notice['context']['environment'] = 'production';
    return $notice;
});

从通知中过滤敏感数据

$notifier->addFilter(function ($notice) {
    if (isset($notice['params']['password'])) {
        $notice['params']['password'] = 'FILTERED';
    }
    return $notice;
});

忽略特定异常

$notifier->addFilter(function ($notice) {
    if ($notice['errors'][0]['type'] == 'MyExceptionClass') {
        // Ignore this exception.
        return null;
    }
    return $notice;
});

向通知添加用户数据

$notifier->addFilter(function ($notice) {
    $notice['context']['user']['name'] = 'Avocado Jones';
    $notice['context']['user']['email'] = 'AJones@guacamole.com';
    $notice['context']['user']['id'] = 12345;
    return $notice;
});

设置严重性

严重性允许对错误的严重程度进行分类。默认情况下，它设置为error。要重新定义严重性，只需覆盖通知对象的context/severity即可。例如

$notice = $notifier->buildNotice($e);
$notice['context']['severity'] = 'critical';
$notifier->sendNotice($notice);

错误处理器

通知器可以处理PHP错误、未捕获的异常和关闭。您可以使用以下代码注册适当的处理器

$handler = new Airbrake\ErrorHandler($notifier);
$handler->register();

在内部，$handler->register执行以下操作

set_error_handler([$this, 'onError'], error_reporting());
set_exception_handler([$this, 'onException']);
register_shutdown_function([$this, 'onShutdown']);

Laravel集成

请参阅https://github.com/TheoKouzelis/laravel-airbrake

Symfony集成

请参阅https://github.com/aminin/airbrake-bundle

CakePHP 3.x集成

请参阅https://gist.github.com/mauriciovillalobos/01a97f9ee6179ad70b17d54f37cc5010

Zend Framework集成

请参阅https://github.com/FrankHouweling/zend-airbrake

Monolog集成

$log = new Monolog\Logger('billing');
$log->pushHandler(new Airbrake\MonologHandler($notifier));

$log->addError('charge failed', ['client_id' => 123]);

额外配置选项

appVersion

您可以将其传递给应用程序版本，以区分多个版本之间的异常。默认情况下不设置。

$notifier = new Airbrake\Notifier([
    // ...
    'appVersion' => '1.2.3',
    // ...
]);

host

默认情况下设置为api.airbrake.io。一个host是一个包含方案（"http"或"https"）、主机和端口的Web地址。您可以省略端口号（默认为80）和方案（默认为"https"）。

$notifier = new Airbrake\Notifier([
    // ...
    'host' => 'errbit.example.com', // put your errbit host here
    // ...
]);

remoteConfig

配置远程配置功能。每10分钟通知器会向Airbrake服务器发送GET请求，获取包含项目配置设置的JSON文档。通知器将在运行时应用这些新设置。默认情况下启用。

要禁用此功能，请使用以下配置通知器

$notifier = new Airbrake\Notifier([
    // ...
    'remoteConfig' => false,
    // ...
]);

注意：不建议禁用此功能。它可能会对通知器的工作方式产生负面影响。请谨慎使用此选项。

rootDirectory

配置项目的根目录。期望是一个字符串或路径名，表示项目的路径。提供此选项有助于我们从堆栈跟踪帧中过滤重复数据，并从我们的仪表板链接到GitHub文件。

$notifier = new Airbrake\Notifier([
    // ...
    'rootDirectory' => '/var/www/project',
    // ...
]);

环境

配置应用程序运行的环境。帮助Airbrake仪表板区分不同环境中发生的异常。默认情况下，它未设置。

$notifier = new Airbrake\Notifier([
    // ...
    'environment' => 'staging',
    // ...
]);

httpClient

配置必须实现GuzzleHttp\ClientInterface的底层http客户端。

// Supply your own client.
$client = new Airbrake\Http\GuzzleClient(
    new GuzzleHttp\Client(['timeout' => 3])
);

$notifier = new Airbrake\Notifier([
    // ...
    'httpClient' => $client,
    // ...
]);

过滤键

使用keysBlocklist选项，您可以指定包含必须过滤的敏感信息的键的列表，例如。

$notifier = new Airbrake\Notifier([
    // ...
    'keysBlocklist' => ['/secret/i', '/password/i'],
    // ...
]);

运行测试

通过docker运行

docker compose run tests

或本地运行

composer install
vendor/bin/phpunit

PHPDoc

composer require phpdocumentor/phpdocumentor
vendor/bin/phpdoc -d src
firefox output/index.html

联系

如果您遇到问题、有疑问或要提交错误报告，请随时

• 提交问题
• 给我们发邮件

许可证

PHPBrake在MIT许可证（MIT）下授权。