README

Sentry for Laravel

Laravel 对 Sentry 的集成。

Laravel 版本兼容性

• Laravel 4.2.x 支持 0.8.x 版本 (composer require "sentry/sentry-laravel:0.8.*")
• Laravel 5.x.x 支持最新版本 (composer require sentry/sentry-laravel)

安装

Laravel 5.x

安装 sentry/sentry-laravel 包

$ composer require sentry/sentry-laravel

如果你使用的是 Laravel 5.4 或更早版本，需要在 config/app.php 中添加以下内容

'providers' => array(
    // ...
    Sentry\SentryLaravel\SentryLaravelServiceProvider::class,
)

'aliases' => array(
    // ...
    'Sentry' => Sentry\SentryLaravel\SentryFacade::class,
)

在 app/Exceptions/Handler.php 中添加 Sentry 报告

public function report(Exception $exception)
{
    if (app()->bound('sentry') && $this->shouldReport($exception)) {
        app('sentry')->captureException($exception);
    }

    parent::report($exception);
}

创建 Sentry 配置文件 (config/sentry.php)

$ php artisan vendor:publish --provider="Sentry\SentryLaravel\SentryLaravelServiceProvider"

将你的 DSN 添加到 .env

SENTRY_LARAVEL_DSN=https://public:secret@sentry.example.com/1

注意： 如果你在 .env 中使用 SENTRY_DSN，它将覆盖 config/sentry.php 文件中设置的 DSN 值。

Laravel 4.x

由于它是支持 Laravel 4 的最后一个版本，因此需要在 0.8.* 版本上安装 sentry/sentry-laravel 包

$ composer require "sentry/sentry-laravel:0.8.*"

在 config/app.php 中添加 Sentry 服务提供者和外观

'providers' => array(
    // ...
    'Sentry\SentryLaravel\SentryLaravelServiceProvider',
)

'aliases' => array(
    // ...
    'Sentry' => 'Sentry\SentryLaravel\SentryFacade',
)

创建 Sentry 配置文件 (config/sentry.php)

$ php artisan config:publish sentry/sentry-laravel

Lumen 5.x

安装 sentry/sentry-laravel 包

$ composer require sentry/sentry-laravel

在 bootstrap/app.php 中注册 Sentry

$app->register('Sentry\SentryLaravel\SentryLumenServiceProvider');

# Sentry must be registered before routes are included
require __DIR__ . '/../app/Http/routes.php';

在 app/Exceptions/Handler.php 中添加 Sentry 报告

public function report(Exception $e)
{
    if (app()->bound('sentry') && $this->shouldReport($e)) {
        app('sentry')->captureException($e);
    }

    parent::report($e);
}

创建 Sentry 配置文件 (config/sentry.php)

<?php

return array(
    'dsn' => '___DSN___',

    // capture release as git sha
    // 'release' => trim(exec('git log --pretty="%h" -n1 HEAD')),

    // Capture bindings on SQL queries
    'breadcrumbs.sql_bindings' => true,

    // Capture default user context
    'user_context' => false,
);

使用 Artisan 进行测试

您可以使用提供的 artisan 命令测试您的配置

$ php artisan sentry:test
[sentry] Client configuration:
-> server: https://app.getsentry.com/api/3235/store/
-> project: 3235
-> public_key: e9ebbd88548a441288393c457ec90441
-> secret_key: 399aaee02d454e2ca91351f29bdc3a07
[sentry] Generating test event
[sentry] Sending test event with ID: 5256614438cf4e0798dc9688e9545d94

添加上下文

添加上下文的机制将根据您使用的 Laravel 版本而有所不同，但一般方法相同。找到应用程序中上下文可用的良好入口点，理想情况下是在处理过程的早期。

以下示例中，我们将使用中间件

namespace App\Http\Middleware;

use Closure;

class SentryContext
{
    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request $request
     * @param  \Closure                 $next
     *
     * @return mixed
     */
    public function handle($request, Closure $next)
    {
        if (app()->bound('sentry')) {
            /** @var \Raven_Client $sentry */
            $sentry = app('sentry');

            // Add user context
            if (auth()->check()) {
                $sentry->user_context([...]);
            } else {
                $sentry->user_context(['id' => null]);
            }

            // Add tags context
            $sentry->tags_context([...]);
        }

        return $next($request);
    }
}

显示错误 ID

当出现问题并收到客户电子邮件时，如果他们能提供一些关于他们看到错误的标识符，那将很有帮助。

幸运的是，Sentry 通过在错误视图中添加以下选项之一为您提供这样的标识符。

// Using the Sentry facade
$errorID = Sentry::getLastEventID();

// Or without the Sentry facade (Lumen)
$errorID = app('sentry')->getLastEventID();

例如，这可以看起来像这样在你的 resources/views/error/500.blade.php

@if(!empty(Sentry::getLastEventID()))
    <p>Please send this ID with your support request: {{ Sentry::getLastEventID() }}.</p>
@endif

您可以在 Sentry 界面中搜索此 ID，以便快速找到错误。

使用 Laravel 5.6 日志通道

要将 Sentry 配置为日志通道，请将以下配置添加到 config/logging.php 中的 channels 部分

'channels' => [
    // ...
    'sentry' => [
        'driver' => 'sentry',
    ],
],

配置 Sentry 日志通道后，您可以通过修改日志堆栈来配置应用程序同时记录到日志文件和 Sentry

'channels' => [
    'stack' => [
        'driver' => 'stack',
        // Add the Sentry log channel to the stack
        'channels' => ['single', 'sentry'],
    ],
    //...
],

可选地，您可以设置日志级别以及是否应在驱动程序上冒泡事件

'channels' => [
    // ...
    'sentry' => [
        'driver' => 'sentry',
        'level'  => null, // The minimum monolog logging level at which this handler will be triggered
                          // For example: `\Monolog\Logger::ERROR`
        'bubble' => true, // Whether the messages that are handled can bubble up the stack or not
    ],
],

解决与也称为 Sentry 的包的命名冲突

为了解决这个问题，您需要创建一个扩展我们自己的服务提供者的服务提供者，这样我们就可以防止命名冲突。

<?php

namespace App\Support;

class SentryLaravelServiceProvider extends \Sentry\SentryLaravel\SentryLaravelServiceProvider
{
    public static $abstract = 'sentry-laravel';
}

然后您可以将此服务提供者添加到 config/app.php。

'providers' => array(
    // ...
    App\Support\SentryLaravelServiceProvider::class,
)

如果还想使用外观，还需要扩展或创建一个新的外观。

<?php

namespace App\Support;

class SentryLaravelFacade extends \Sentry\SentryLaravel\SentryFacade
{
    protected static function getFacadeAccessor()
    {
        return 'sentry-laravel';
    }
}

然后将该外观添加到 config/app.php。

'aliases' => array(
    // ...
    'SentryLaravel' => App\Support\SentryLaravelFacade::class,
)

添加您自己的服务提供者后，运行 php artisan vendor:publish --provider="App\Support\SentryLaravelServiceProvider" 将 Sentry 配置文件发布到您选择的名字（在上面的示例中为 config/sentry-laravel.php），从而防止与其他包可能使用的 config/sentry.php 配置文件冲突。

如果您遵循了上述常规安装说明（您应该这样做），请确保将 app('sentry') 替换为 app('sentry-laravel')。

示例中上面的 \App\Support 命名空间可以是您想要的任何内容。

注意：如果您使用的是 Laravel 5.5+，则 Sentry 包可能已经被 Laravel 自动发现。为了解决这个问题，请在您的 composer.json 文件中的 extra 部分添加或追加内容，然后运行 composer update/install。

"extra": {
    "laravel": {
        "dont-discover": ["sentry/sentry-laravel"]
    }
}

贡献

依赖项通过 composer 管理

$ composer install

然后可以通过 phpunit 运行测试

$ vendor/bin/phpunit

社区

• 错误追踪器
• 代码
• 邮件列表
• IRC (irc.freenode.net, #sentry)