README

kRAKEN 是一个用于跟踪和管理外部应用程序产生的错误的程序

此库提供了一个 PHP 客户端API，以简化对 kRAKEN 的调用，并为 Laravel 和 Phalcon 框架提供了集成

集成添加了一个 ExceptionHandler，它执行未捕获异常的完整报告，以及一个 Logger，允许您使用 kRAKEN 系统接收和存档日志消息

目录

• 入门
• Laravel集成
  • 集成
  • ExceptionHandler使用
  • Logger使用
  • 自定义
• Phalcon集成
  • 集成
  • ExceptionHandler使用
  • Logger使用
  • 自定义

入门

需要 PHP 8.1+

首先，通过 Composer 包管理器安装 Kraken 客户端

composer require shellrent/kraken-client

然后与 kRAKEN 的 API 交互以发送报告

$report = new \Shellrent\KrakenClient\ReportBuilder( 
  'report-type', //Corresponds to the type code configured on the project on kRAKEN app
  'message' //Message to send
);

$client = new \Shellrent\KrakenClient\KrakenClient( 
  'https://kraken-endpoint.com', //kRAKEN endpoint 
  'auth-token' //Create an "environment" on the project page on kRAKEN app
);

$client->sendReport( $report->getData() );

要从异常生成标准报告，只需使用特定的 ReportBuilder 方法即可

try {
    /* code that throws an exception */
    
} catch( Exception $exception ) {
    $report = new \Shellrent\KrakenClient\ReportBuilder::createFromException( $exception );
    
    /* send the report */
}

Laravel

需要 Laravel 10.x

ExceptionHandler 也可以与 Laravel 9.x 一起使用

之前或之后的版本尚未测试

在其他版本上的使用存在风险，请自行承担

存在与 Laravel 框架的集成

Laravel 包提供了一个 ExceptionHandler 并在服务容器中注册了 client API 和 psr 风格的 logger

集成（Laravel）

要使该包正常工作，您需要将以下设置添加到 .env 文件中

KRAKEN_ENDPOINT="https://kraken-endpoint.com"
KRAKEN_AUTH_TOKEN="auth-token"

要能够通过 队列 发送报告，您必须在 .env 文件中指定要使用的队列名称，您可以使用 "default" 值以使用标准队列

KRAKEN_QUEUE_NAME="default"

您可以使用以下命令测试连接到 kraken 以及配置是否正确

php artisan kraken:test

ExceptionHandler使用（Laravel）

要启用通过 Exception Handler 的异常报告，您需要将 Exception Handler 设置在 bootrstrap/app.php 文件中，并覆盖当前配置

$app->singleton(
    Illuminate\Contracts\Debug\ExceptionHandler::class,
    \Shellrent\KrakenClient\Laravel\KrakenExceptionHandler::class
);

您可以通过修改配置文件中的 enabled_envs 来决定在哪些环境中激活报告的发送；默认情况下仅启用 生产 环境

默认情况下，该包不会发送已登录用户的信息，但可以通过在配置文件中设置 user_report_builder 来添加，该可调用的返回此信息

有关更多详细信息，请参阅 laravel自定义

Logger使用（Laravel）

您可以使用 KrakenLogger 的 Facade 发送单个报告和日志

use Shellrent\KrakenClient\Laravel\Facades\KrakenLogger;

KrakenLogger::debug( 'message' );
KrakenLogger::info( 'message' );
KrakenLogger::notice( 'message' );
KrakenLogger::warning( 'message' );
KrakenLogger::error( 'message' );
KrakenLogger::critical( 'message' );
KrakenLogger::alert( 'message' );
KrakenLogger::emergency( 'message' );

另一方面，要使用通过 Laravel 日志系统使用 kraken，您可以在 config/logging.php 配置文件中将 kraken 添加为自定义通道

它也可以与其他通道一起添加到堆栈通道中

/******/
'channels' => [
    /*****/
        'stack' => [
            'driver' => 'stack',
            'channels' => ['daily', 'kraken'],
            'ignore_exceptions' => false,
        ],
        /*****/
        'kraken' => [
            'driver' => 'kraken',
            'level' => env('LOG_LEVEL', 'debug'),
            'report_exceptions' => false,
        ],
    /*****/
]

您可以将 kraken 日志通道用作 Exception Handler 的替代品，只需在配置中将 'report_exceptions' => true 设置为 true 即可

警告

不要同时使用设置 'report_exceptions' => true 的 Exception Handler 和日志通道，否则在发生异常时会 重复 发送的报告

自定义（Laravel）

要修改配置，您必须首先通过以下命令发布它：

php artisan vendor:publish --provider="Shellrent\KrakenClient\Laravel\KrakenServiceProvider"

您可以从在 config/kraken.php 中创建的文件中编辑

• 框架使用的标准模块的代码
• 触发 ExceptionHandler 的环境
• 异常报告的类型代码和构建类
• 日志报告的类型代码和构建类
• 已登录用户信息

更多详细信息，请参阅 配置文件

Phalcon

需要 Phalcon 5.1

之前或之后的版本尚未测试

在其他版本上的使用存在风险，请自行承担

与 Phalcon 框架有集成

Phalcon 的集成提供了一个 ExceptionHandler，并允许您通过框架的 DI 容器获取 配置 和 psr 风格的日志记录器

集成（Phalcon）

要使该包正常工作，您需要将以下设置添加到 .env 文件中

KRAKEN_API_ENDPOINT="https://kraken-endpoint.com"
KRAKEN_API_TOKEN="auth-token"

ExceptionHandler 使用（Phalcon）

要发送异常报告，必须将 phalcon 包中提供的 ExceptionHandler 与应用程序使用的 ExceptionHandler 集成

您可以选择在哪些环境中激活报告的发送，通过将环境集合传递给 ExceptionHandler。默认激活的环境是 production

$envs = ['production'];
$krakenHandler = \Shellrent\KrakenClient\Phalcon\KrakenExceptionHandler::create( $envs )
$krakenHandler->report( $exception, $errno, $errstr, $errfile, $errline, $backtrace );

处理器处理异常和 PHP 错误

您可以通过 addSessionKey 方法向报告添加会话部分

$krakenHandler->addSessionKey( 'logged-used' );

此外，通过传递标识它的键或值，还可以在报告中隐藏特定信息。如果在 $_SERVER 或其他集合中存在敏感数据，则很有用

$krakenHandler->addHideDataKey( getenv( 'DATABASE_PASSWORD' ) );
$krakenHandler->addHideDataKey( 'KEY_CLI_ACCESS' );

默认情况下，该包不发送已登录用户的信息，可以通过在配置对象中设置 userDataGetter 属性来添加，该属性是一个返回此信息的可调用对象

更多详细信息，请参阅 Phalcon 定制

Logger 使用（Phalcon）

您可以通过使用 KrakenService 使用 KrakenLogger 发送单个报告和日志

$logger = \Shellrent\KrakenClient\Phalcon\KrakenService::logger();

$logger->debug( 'message' );
$logger->info( 'message' );
$logger->notice( 'message' );
$logger->warning( 'message' );
$logger->error( 'message' );
$logger->critical( 'message' );
$logger->alert( 'message' );
$logger->emergency( 'message' );

定制（Phalcon）

虽然不是必需的，但为了定制包的行为，需要在 DI 中注册服务

abstract class GenericApplication {
  /******/
  
  private function registerServices() {
      /******/
      $config = \Shellrent\KrakenClient\Phalcon\Config\Config::default();
      \Shellrent\KrakenClient\Phalcon\KrakenService::create( $config )->inject( $this->Di );
  } 
}

可以定制配置对象以进行更改

• 异常报告的类型代码和构建类
• PHP 错误报告的构建类
• 日志报告的类型代码和构建类
• 已登录用户信息

更多详细信息，请参阅 配置类