README

Raygun.com的PHP 7.2+提供商

查看v1.8文档了解对PHP v5.3+的支持

安装

Raygun4PHP使用Guzzle处理数据到Raygun API的传输。建议安装cURL，但不是必需的，因为如果未安装cURL，Guzzle将使用PHP流包装器。

使用Composer

Composer是PHP的包管理工具，它可以自动获取依赖项，并支持自动加载 - 这是一种低影响力的方法，可以将Raygun4PHP集成到您的网站上。

1. 如果您使用*nix环境，请遵循说明安装Composer。Windows用户可以运行此安装程序以自动将其添加到Path。

2. 在您项目的根目录下创建一个composer.json文件，包含

{
    "require": {
        "mindscape/raygun4php": "^2.0"
    }
}

3. 从您的shell运行php composer.phar install (*nix)或composer install (Windows)。这将下载Raygun4PHP并创建适当的自动加载数据。

4. 然后在PHP文件中添加

require_once 'vendor/autoload.php';

库将导入并准备好使用。

用法

您可以自动将PHP错误和面向对象的异常发送到Raygun。RaygunClient需要一个HTTP传输（例如Guzzle或其他PSR-7兼容接口）。

提供程序中有基于Guzzle的异步和同步传输类，或者您可以使用自己的。

异步传输

以下是一个异步发送错误和异常的基本用法示例

<?php
namespace {
    require_once 'vendor/autoload.php';

    use GuzzleHttp\Client;
    use Raygun4php\RaygunClient;
    use Raygun4php\Transports\GuzzleAsync;

    $httpClient = new Client([
        'base_uri' => 'https://api.raygun.com',
        'timeout' => 2.0,
        'headers' => [
            'X-ApiKey' => 'INSERT_API_KEY_HERE'
        ]
    ]);

    $transport = new GuzzleAsync($httpClient);

    $raygunClient = new RaygunClient($transport);

    set_error_handler(function($errno, $errstr, $errfile, $errline) use ($raygunClient) {
        $raygunClient->SendError($errno, $errstr, $errfile, $errline);
    });

    set_exception_handler(function($exception) use ($raygunClient) {
        $raygunClient->SendException($exception);
    });

    register_shutdown_function(function() use ($raygunClient) {
        $lastError = error_get_last();

        if (!is_null($lastError)) {
            [$type, $message, $file, $line] = $lastError;
            $raygunClient->SendError($type, $message, $file, $line);
        }
    });

    register_shutdown_function([$transport, 'wait']);
}

同步传输

对于同步传输，使用上面的代码片段，但将use Raygun4php\Transports\GuzzleAsync;替换为

use Raygun4php\Transports\GuzzleSync;

并将$transport = new GuzzleAsync($httpClient);替换为

$transport = new GuzzleSync($httpClient);

删除此行

register_shutdown_function([$transport, 'wait']);

请注意，如果您将其放置在具有您选择的命名空间的文件中，则上述代码应声明为在全局命名空间内（因此需要namespace { }）。您还需要在创建$raygunClient实例之前使用上述require语句（自动加载或手动）。

从Raygun应用复制您的应用程序的API密钥，并将其粘贴到HTTP客户端的“X-ApiKey”头部字段中。

如果处理程序位于自己的文件中，只需将其导入到您希望发送异常和错误的每个文件中，它们将被发送到Raygun。

配置

代理

可以将URL设置为HTTP客户端的“proxy”属性

// ...

$httpClient = new Client([
    'base_uri' => 'https://api.raygun.com',
    'proxy' => 'http://someproxy:8080',
    'headers' => [
        'X-ApiKey' => 'INSERT_API_KEY_HERE'
    ]
]);

有关更多选项，请参阅Guzzle的代理文档。

使用日志记录器进行调试

我们建议使用兼容PSR-3 LoggerInterface（例如Monolog）的日志记录器。

在上述的异步传输示例中进一步扩展，您可以设置一个用于传输的日志记录器，如下所示

// ...

use Monolog\Handler\FirePHPHandler;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;

// ...

$logger = new Logger('my_logger');
$logger->pushHandler(new StreamHandler(__DIR__ . '/debug.log'));
$logger->pushHandler(new FirePHPHandler());

// Create $httpClient ...

$transport = new GuzzleAsync($httpClient);
$transport->setLogger($logger);

$raygunClient = new RaygunClient($transport);

// Set error handlers ...

响应代码

• 202：Raygun API正确接收到消息
• 400：错误请求。这可能表示有效载荷无效 - 如果您继续看到此问题，请联系Raygun。
• 403：无效的API密钥。从Raygun应用设置说明或应用程序设置中复制API密钥。

版本号

您可以在实例化RaygunClient后通过调用SetVersion()将PHP项目的版本号与消息一起传输 - 这不是必需的，但建议这样做，因为版本号被视为消息的一等数据。

$raygunClient = new RaygunClient($transport);
$raygunClient->SetVersion('1.0.0.0');

添加标签

标签可以添加到错误数据中，以提供额外信息和帮助在Raygun中过滤错误。它们作为字符串或数字数组提供，作为SendError函数的第5个参数或作为SendException函数的第2个参数传递。

添加标签到每个有效载荷的异常和错误处理器的声明可能如下所示

<?php
// ...

$raygunClient = new RaygunClient($transport);

$tags = ['staging-environment', 'machine-4'];

set_error_handler(function($errno, $errstr, $errfile, $errline) use ($raygunClient, $tags) {
    $raygunClient->SendError($errno, $errstr, $errfile, $errline, $tags);
});

set_exception_handler(function($exception) use ($raygunClient, $tags) {
    $raygunClient->SendException($exception, $tags);
});

register_shutdown_function(function() use ($raygunClient, $tags) {
    $lastError = error_get_last();

    if (!is_null($lastError)) {
        [$type, $message, $file, $line] = $lastError;
        $raygunClient->SendError($type, $message, $file, $line, $tags);
    }
});

// ...

您可以通过以下方式手动发送已处理的异常并添加标签

try {
    // Do something questionable...
} catch(Exception $exception) {
    $raygunClient->SendException($exception, ['handled-exception']);
}

受影响用户跟踪

您可以通过传递以下数据（部分或全部）调用$raygunClient->SetUser，这将用于提供受影响用户计数和报告

$raygunClient->SetUser($user = 'email_or_unique_identifier', $firstName = 'Example', $fullName = 'Example User', $emailAddress = 'test@example.com', $isAnonymous = false, $uuid = 'abc123');

$user应是一个唯一标识符，用于识别您的用户。如果您将其设置为他们的电子邮件地址，请确保也设置了$email参数。

如果出于隐私考虑希望禁用此功能，则此功能和值是可选的。要这样做，请将true作为RaygunClient构造函数的第二个参数传递。

// Disable user tracking:
$raygunClient = new RaygunClient($transport, true);

请注意，此数据存储为cookie。如果您没有调用SetUser，默认情况下将存储一个随机的UUID来表示用户。

此功能可以通过在会话开始时调用SetUser()在CLI模式下使用。

自定义错误分组

通过向客户端的SetGroupingKey方法传递回调，可以控制如何将错误实例分组在一起。如果回调返回一个字符串（理想情况下不超过100个字符），则匹配该键的错误将分组在一起，覆盖默认的自动分组。如果回调返回一个非字符串值，则该错误将自动分组。

$raygunClient->SetGroupingKey(function($payload, $stackTrace) {
    // Inspect the above parameters and return a hash from the properties ...
    return $payload->Details->Error->Message; // Naive message-based grouping only
});

过滤敏感数据

某些错误数据可能过于敏感，无法发送到外部服务，例如信用卡详情或密码。由于此数据非常特定于应用程序，Raygun默认不进行过滤。您可以根据其键配置以替换或以其他方式转换特定值。这些转换适用于表单数据（$_POST）、自定义用户数据、HTTP头和环境数据（$_SERVER）。它不过滤URL或其$_GET参数，或自定义消息字符串。由于Raygun不在堆栈跟踪中记录方法参数，因此不需要过滤。所有键比较均不区分大小写。

$raygunClient->setFilterParams([
    'password' => true,
    'creditcardnumber' => true,
    'ccv' => true,
    'php_auth_pw' => true, // filters basic auth from $_SERVER
]);
// Example input: ['Username' => 'myuser','Password' => 'secret']
// Example output: ['Username' => 'myuser','Password' => '[filtered]']

您还可以将键定义为正则表达式

$raygunClient->setFilterParams([
    '/^credit/i' => true,
]);
// Example input: ['CreditCardNumber' => '4111111111111111','CreditCardCcv' => '123']
// Example output: ['CreditCardNumber' => '[filtered]','CreditCardCcv' => '[filtered]']

如果您想保留有关数据的某些提示而不是完全删除它，您还可以通过PHP的匿名函数应用自定义转换。以下示例截断以"address"开头的所有键。

$raygunClient->setFilterParams([
    'Email' => function($key, $val) {return substr($val, 0, 5) . '...';}
]);
// Example input: ['Email' => 'test@test.com']
// Example output: ['Email' => 'test@...']

如果您想确保无论字段名称如何都过滤掉所有表单提交数据，对于存在大量可能请求私人信息的表单的情况，您也可以这样做。字段名称将仍然传输，但值将被过滤掉。

$raygunClient->setFilterAllFormValues(true);

请注意，当定义任何过滤器时，Raygun错误将不再包含原始HTTP数据，因为没有有效的方法来过滤它。

更新Cookie选项

Cookies用于Raygun4PHP提供者用户跟踪功能。在提供者的1.8版本中，现在可以将传递给setcookie方法的选项自定义到您的需求。

$raygunClient->SetCookieOptions([
    'expire'   => 2592000, // 30 * 24 * 60 * 60
    'path'     => '/',
    'domain'   => '',
    'secure'   => false,
    'httponly' => false
]);

故障排除

如上所述，您可以为HTTP传输指定记录器

$transport->setLogger($logger);

这将记录在向Raygun传输数据时发生的异常。如果您继续遇到问题，请创建问题或联系我们。

命令行Posix环境中的400错误

如果在*nix操作系统上从命令行运行PHP脚本时，您收到一个'400 Bad Request'错误（在您的调试日志中），请检查您是否设置了任何LESS_TERMCAP环境变量。这些变量与Raygun4PHP的当前版本不兼容。作为解决方案，在您的脚本运行之前取消设置这些变量，然后之后重新设置它们。

错误控制运算符（@）

如果您使用的是上述设置，则错误将发送到Raygun，无论是否有任何前面带有错误控制运算符（@符号）的行。要阻止这些错误发送到Raygun，您可以调用PHP的error_reporting方法，如果触发错误之前有@符号，该方法将返回0。

错误处理程序示例

function ($errno, $errstr, $errfile, $errline) use ($raygunClient) {
    if (error_reporting() !== 0) {
        $raygunClient->SendError($errno, $errstr, $errfile, $errline);
    }
}

有关更多信息，请参阅PHP.net上的错误控制运算符部分。

变更日志

• 2.3.2：修复使用setcookie()不保存null值的问题
• 2.3.1：使用iconv从ISO-8859-1转换，而不是utf8_encode
• 2.3.0：支持psr/log的新版本
• 2.2.1：SetUser方法现在支持'用户'参数的数字数据类型
• 2.2.0：捕获异常本身抛出的文件和行号
• 2.1.1：修复在Uuid库中命名空间的问题，以防止与混合大小写包名称的composer错误
• 2.1.0：允许过滤客户端IP地址，添加配置以过滤所有POST表单数据
• 2.0.2：在Travis构建中移除PHP 7.2并替换为PHP 8.0，修复单元测试中的JSON匹配断言问题
• 2.0.1：修复CLI使用问题，RaygunMessage JSON编码中的PHP 7.4弃用警告
• 2.0.0：新主要版本
  • 将最低PHP版本提高到7.1
  • 添加PSR-4自动加载器
  • 从RaygunClient类中删除toJsonRemoveUnicodeSequences和removeNullBytes方法 - 使用toJson代替
• 1.8.4：PHPUnit和配置更新，PHPDoc修复，以及从cookie中获取用户ID时的空指针异常修复
• 1.8.3：移除composer安装中的--dev选项，因为它已被弃用
• 1.8.2：当套接字连接失败时不再输出警告
• 1.8.1：修复使用escapeshellarg方法发送null字节时引发的错误
• 1.8.0：修复设置多个cookie的bug。可以通过setCookieOptions方法设置cookie选项
• 1.7.1：修复非法字符串偏移量问题
• 1.7.0：添加自定义错误分组
• 1.6.1：将ClassName分配为exceptionClass
• 1.6.0：添加HTTP代理支持，支持X-Forwarded-For，null服务器变量保护
• 1.5.3：统一属性大小写（内部更改）
• 1.5.2：防止当query_string不在$_SERVER中时出错
• 1.5.1：防止间歇性用户ID cookie为null；为禁用用户跟踪提供重载
• 1.5.0：添加增强的用户数据支持；修复1.4中可能出现的null backtrace frames
• 1.4.0：添加敏感数据过滤；改进错误回溯；启用Travis CI
• 1.3.6：将包含的Rhumsaa\Uuid库移动到此命名空间，以防止发生冲突
• 1.3.5：修复异步curl逻辑中的可能bug
• 1.3.4: 修复测试请求消息中的错误
• 1.3.3: 修复 v1.3.2 中脚本错误的紧急修复
• 1.3.2: 将之前版本的 UTF-8 编码程序更新为移除已废弃的 PHP 5.5 函数
• 1.3.1: 请求数据，特别是 $_SERVER 变量，现在已正确以 UTF-8 编码
• 1.3: 添加调试模式，在套接字模式下输出 HTTP 响应代码
• 1.2.6: 修复了上一个版本中渲染 UTC 偏移量修复无效的错误（感谢 @mrardon 发现此问题）
• 1.2.5: 将请求的 rawData（php://input）限制为 4096 字节，与其他提供商保持一致；将 UTC 偏移量限制在合理的值，因为 API 发现一些条目具有最大整型偏移量
• 1.2.4: 合并了单元测试
• 1.2.3: 修复了一个错误，其中 OccurredOn 未能以正确的 ISO 8601 表示形式出现
• 1.2.2: 些微的格式化重构
• 1.2.1: 修复了多个与用户跟踪和请求处理相关的错误
• 1.2: 添加了新的异步发送函数；移除了 cURL 依赖
• 1.1: 添加了用户跟踪支持；改进了 CLI 模式下的体验；添加了用户指定的时间戳支持；修复了用户数据编码错误
• 1.0: 初始提交