README

为您的Laravel应用程序或网站提供服务器端分析。没有cookies，没有跟踪 :)

愿景

当涉及到您的Web项目的分析时，有很多选择。随着《通用数据保护条例》（GDPR）的推进，隐私保护成为了一个重点。消费者现在意识到他们可以在整个网络中被跟踪，并且对此并不欣赏。

当您开发下一个网站或项目时，您可能希望添加分析功能，以便了解您获得了多少页面浏览量等。您可能不关心特定访客是如何到达您的网站，或者他们在那里采取了哪些行动。您只需要了解您的Web项目活动的一些基本指标。

您来对地方了。

目标

完全由后端处理：这意味着不需要添加到您网站的客户端JS，这意味着不会影响用户的性能
写操作不应影响请求性能
可定制：我们将跟踪请求的主要方面（路径、状态、参数、持续时间、用户等），但同时也允许您向请求附加额外数据（例如访问了数据库中的哪个实体或元数据）
附带默认仪表板以查看您的数据：我们将为您提供默认仪表板（和单独的路由）来查看您的数据
可访问的API：除了默认仪表板外，我们还将公开一个API，您可以使用它从数据中提取自定义指标

安装

您可以通过composer安装此包

composer require ohseesoftware/laravel-server-analytics

发布包（配置、资源等）

php artisan vendor:publish --provider="OhSeeSoftware\LaravelServerAnalytics\LaravelServerAnalyticsServiceProvider"

审查配置文件并根据需要做出更改

config/laravel-server-analytics.php

运行数据库迁移

php artisan migrate

用法

基本用法

对于基本请求跟踪，除了包含中间件外，您不需要在应用程序中添加任何自定义代码

// Kernel.php

protected $middleware = [
  // ... other middlware here
  \OhSeeSoftware\LaravelServerAnalytics\Http\Middleware\LogRequest::class,
];

如果您只想跟踪特定的中间件组，请将其添加到该组，而不是全局的$middleware变量。

跟踪认证用户

v3.0.0+

默认情况下，该包将自动跟踪发起请求的认证用户。这直接存储在analytics表的user_id列中。

默认迁移假定您的用户存储在具有BIGINT字段类型的users表中，主键。如果您的用户不是这样存储的，您应该编写自己的迁移。该包还假定您的User模型位于App\User。如果您的位于不同的命名空间中，您可以在发布的配置文件中更新user_model键。

当记录请求时，该包将使用此代码将user_id插入到analytics表中

$userId = $request->user()?->id ?? null

排除路由

如果您想排除特定路由（或通配符）的跟踪，可以通过addRouteExclusions()方法实现。

// AppServiceProvider

use OhSeeSoftware\LaravelServerAnalytics\Facades\ServerAnalytics;

public function boot()
{
    // Do not track `/home` or `/admin/*` routes
    ServerAnalytics::addRouteExclusions([
      '/home',
      '/admin/*'
    ]);
}

排除请求方法

如果您想排除特定请求方法的跟踪，可以通过addMethodExclusions()方法实现。

// AppServiceProvider

use OhSeeSoftware\LaravelServerAnalytics\Facades\ServerAnalytics;

public function boot()
{
    // Do not track `POST` or `PUT` requests
    ServerAnalytics::addMethodExclusions(['POST', 'PUT']);
}

排除来自爬虫的请求

如果您想排除来自爬虫/爬虫的请求，可以将ignore_bot_requests配置值设置为true。

我们使用Crawl Detect包来检测爬虫。

// config/laravel-server-analytics.php

return [
    'ignore_bot_requests' => true
];

请求钩子

我们提供了可选的钩子，您可以使用它们来自动将额外数据关联到您的分析记录中：addMetaHook和addRelationHook。这两个钩子都返回应与分析记录关联的数据数组。您可以在请求的生命周期内添加任意数量的这些钩子。

addMetaHook示例

ServerAnalytics::addMetaHook(function (RequestDetails $requestDetails) {
    return [
        'key' => 'some-key',
        'value' => 'some-value'
    ];
});

addRelationHook示例

ServerAnalytics::addRelationHook(function (RequestDetails $requestDetails) use ($post) {
    return [
        'model' => $post,
        'reason' => 'Post that was deleted.'
    ];
});

还有一些辅助方法可供您使用，这些方法会为您调用上述钩子

ServerAnalytics::addMeta('test', 'value');

ServerAnalytics::addRelation($post);

提供自定义请求详情

我们提供了合理的默认设置来提取请求的详细信息。然而，如果您需要以不同的方式提取详细信息，您可以为RequestDetails类提供自定义实现。

// CustomRequestDetails.php

use OhSeeSoftware\LaravelServerAnalytics\RequestDetails;

class CustomRequestDetails extends RequestDetails
{
    public function getMethod(): string
    {
        // Set the stored `method` as "TEST" for all requests
        return 'TEST';
    }
}

有一个配置值，request_details_class，您可以将其设置为您的请求详情类的完全限定名。当记录请求时，我们将尝试从容器中解析该类。

查询分析记录

您可以使用AnalyticsRepository从分析表中查询数据。如果您需要构建自定义查询，您可以使用仓库实例上的query()方法。

use OhSeeSoftware\LaravelServerAnalytics\Repositories\AnalyticsRepository;

public function loadAnalytics(AnalyticsRepository $analytics)
{
    $records = $analytics->query()->where('method', 'GET')->get();
}

在Analytics模型上还设置了一些查询作用域。

过滤与给定模型相关的分析记录

use OhSeeSoftware\LaravelServerAnalytics\Models\Analytics;

$analytics = Analytics::relatedTo($user);

过滤具有给定键的元数据的分析记录

use OhSeeSoftware\LaravelServerAnalytics\Models\Analytics;

$analytics = Analytics::hasMeta('foo');

过滤具有给定元数据键/值对的分析记录

use OhSeeSoftware\LaravelServerAnalytics\Models\Analytics;

$analytics = Analytics::withMetaValue('foo', 'bar');

测试

./vendor/bin/phpunit

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

安全性

如果您发现任何安全相关的问题，请通过电子邮件security@ohseesoftware.com联系我们，而不是使用问题跟踪器。

ohseesoftware / laravel-server-analytics

维护者

详细信息