README

这是一个简单的模块，它将 Raygun 绑定到 Silverstripe 的错误和异常处理器。

要求

• PHP ^8.1
• Raygun4PHP ^2
• Silverstripe 框架 ^5

Silverstripe 3 的支持可以在版本 ^1 中找到。Silverstripe 4 的支持可以在版本 ^2 和 ^3 中找到。

安装

composer require silverstripe/raygun

配置

将以下内容添加到您的 .env 文件中

SS_RAYGUN_APP_KEY="dwhouq3845y98uiof=="

如果您想跟踪 CMS 中的 JavaScript 错误，您可以在项目的 YAML 配置中激活 LeftAndMainExtension

---
Name: raygunning-left-and-main
---
SilverStripe\Admin\LeftAndMain:
  extensions:
    - SilverStripe\Raygun\LeftAndMainExtension

设置日志级别

您可以在 YAML 配置中定义错误报告级别

SilverStripe\Core\Injector\Injector:
  SilverStripe\Raygun\RaygunHandler:
    constructor:
      client: '%$Raygun4php\RaygunClient'
      level: 'error'

用户跟踪

默认情况下，不会向 Raygun 发送任何用户数据。您可以通过设置一些 yml 配置来选择跟踪登录成员

---
After: raygun
---
Raygun4php\RaygunClient:
  disable_user_tracking: false

SilverStripe\Raygun\RaygunHandler:
  user_main_id_field: 'ID' #default: 'Email'. This is the "Identifier" in the Raygun app.
  user_include_firstname: true #default: false
  user_include_fullname: true #default: false
  user_include_email: true #default: false

多个 Raygun API 密钥（应用密钥）

您可能有多个 Raygun 集成，每个集成都可能使用与默认密钥（由 SS_RAYGUN_APP_KEY 设置）不同的自定义 API 密钥。为此，您需要单独配置每个集成。以下是一些示例

# Here's an example of the LeftAndMainExtension using a custom raygun
# API Key, set through a custom environment variable (SS_CUSTOM_RAYGUN_APP_KEY)

---
Name: custom-raygun-leftnmain-extension
---
SilverStripe\Core\Injector\Injector:
  SilverStripe\Raygun\LeftAndMainExtension.custom:
    class: SilverStripe\Raygun\LeftAndMainExtension
    properties:
      # You'll have to set the SS_CUSTOM_RAYGUN_APP_KEY environment var
      CustomRaygunAppKey: '`SS_CUSTOM_RAYGUN_APP_KEY`'

---
Name: raygunning-left-and-main
After: custom-raygun-leftnmain-extension
---
SilverStripe\Admin\LeftAndMain:
  extensions:
    - SilverStripe\Raygun\LeftAndMainExtension.custom

# Here's an example of a custom Raygun handler for Monolog
# which uses API Key provided by a custom RaygunClientFactory

---
Name: custom-monolog-raygun-handler
---
SilverStripe\Core\Injector\Injector:
  SilverStripe\Raygun\RaygunClientFactory.custom:
    class: SilverStripe\Raygun\RaygunClientFactory
    properties:
      # You'll have to set the SS_CUSTOM_RAYGUN_APP_KEY environment var
      CustomRaygunAppKey: '`SS_CUSTOM_RAYGUN_APP_KEY`'

  Raygun4php\RaygunClient.custom:
    factory: '%$SilverStripe\Raygun\RaygunClientFactory.custom'

  SilverStripe\Raygun\RaygunHandler.custom:
    class: SilverStripe\Raygun\RaygunHandler
    constructor:
      client: '%$Raygun4php\RaygunClient.custom'
      level: 'debug'

  Psr\Log\LoggerInterface:
    calls:
      - [ pushHandler, [ '%$SilverStripe\Raygun\RaygunHandler.custom'] ]

禁用处理器

当 SS_RAYGUN_APP_KEY 环境变量设置时，默认启用 RaygunHandler。可能存在一些需要设置该变量但不需要默认启用处理器的场景（例如，您可能不希望在开发或测试环境中启用处理器，除非通过 BuildTask 触发一些测试异常）。

---
Only:
  environment: 'dev'
---
SilverStripe\Raygun\RaygunHandler:
  enabled: false

然后您可以在 BuildTask 中根据需要启用该处理器。

use SilverStripe\Control\Director;
use SilverStripe\Control\HTTPRequest;
use SilverStripe\Core\Config\Config;
use SilverStripe\Dev\BuildTask;
use SilverStripe\Raygun\RaygunHandler;

class TriggerTestExtensionTask extends BuildTask
{
    protected $title = 'Trigger Test Exception';

    protected $description = 'Throws an exception. Useful for checking raygun integration is working as expected.';

    /**
     * Throw a test exception that is directed through raygun.
     *
     * @param HTTPRequest $request
     */
    public function run($request)
    {
        $env = Director::get_environment_type();
        Config::modify()->set(RaygunHandler::class, 'enabled', true);
        throw new \Exception("Test exception thrown from '$env' environment.");
    }
}

代理

如果您需要通过代理（例如，对于托管在 CWP 上的站点）转发出站请求，您可以通过 yaml 配置设置代理主机和可选端口

SilverStripe\Core\Injector\Injector:
  Raygun4php\RaygunClient:
    constructor:
      proxyHost: '`SS_OUTBOUND_PROXY`'
      proxyPort: '`SS_OUTBOUND_PROXY_PORT`'

过滤

Raygun 将发送以下数据

• $_POST
• $_SERVER
• $_GET（包含在 URL 中）

默认情况下，我们将一些敏感的 Silverstripe 详细信息过滤掉，这些信息出现在 $_SERVER 变量中。包括以下内容

• SS_DATABASE_USERNAME
• SS_DEFAULT_ADMIN_USERNAME
• SS_RAYGUN_APP_KEY
• Cookie 信息（通过 Cookie 和 HTTP_COOKIE）
• 基本认证信息（通过 PHP_AUTH_PW）
• HTTP 认证信息（通过 Authorization 和 HTTP_AUTHORIZATION）
• 包含 PASSWORD、KEY、SECRET 或 TOKEN（不区分大小写）的任何内容

您可能还想过滤掉其他敏感数据，如信用卡号、密码等。您可以在 mysite/_config.php 文件中完成此操作。这些规则应用于 $_SERVER、$_POST 和 $_GET 数据。所有键比较均不区分大小写。

mysite/_config.php 中的示例实现

<?php

$client = Injector::inst()->get(Raygun4php\RaygunClient::class);
$client->setFilterParams(array_merge($client->getFilterParams(), [
    'php_auth_pw' => true,
    '/password/i' => true,
	'Email' => function($key, $val) {
        return substr($val, 0, 5) . '...';
    }
]));

有关接受的过滤格式的更多信息，请参阅 Raygun4php 文档。