README

此Laravel >= 6.0包允许您将视图与Eloquent模型关联。

安装后，您可以执行类似以下操作

// Return total views count
views($post)->count();

// Return total views count that have been made since 20 February 2017
views($post)->period(Period::since('2017-02-20'))->count();

// Return total views count that have been made between 2014 and 2016
views($post)->period(Period::create('2014', '2016'))->count();

// Return total unique views count (based on visitor cookie)
views($post)->unique()->count();

// Record a view
views($post)->record();

// Record a view with a cooldown
views($post)->cooldown(now()->addHours(2))->record();

概述

有时您不想引入第三方服务（如Google Analytics）来跟踪应用的页面访问量。这时，此包就派上用场了。Eloquent Viewable允许您轻松地将视图与Eloquent模型关联。它以简洁为设计理念。

此包将每个视图记录单独存储在数据库中。其优点是可以让我们进行非常具体的计数。例如，如果我们想了解2018年1月10日至2月17日有多少人查看了一个特定的帖子，我们可以这样做：views($post)->period(Period::create('10-01-2018', '17-02-2018'))->count();。其缺点是，根据您应用访问者的数量，您的数据库可能会迅速增大。

特性

以下是一些主要特性

• 将视图与Eloquent模型关联
• 获取总访问量
• 获取特定时间段内的访问量
• 获取唯一访问量
• 获取可查看类型（Eloquent模型类）的访问量
• 按访问量对可查看项排序
• 设置视图之间的冷却时间
• 内置优雅的缓存包装器
• 忽略爬虫、被忽略的IP地址或带有DNT头部的请求的视图

文档

在本文档中，您将找到有关此Laravel包使用的有用信息。

目录

1. 入门
   • 要求
   • 安装
2. 使用
   • 准备您的模型
   • 记录视图
   • 设置冷却时间
   • 检索视图计数
     • 获取总访问量
     • 获取特定时间段内的访问量
     • 获取总唯一视图计数
   • 按视图计数对模型排序
     • 按视图计数排序
     • 按唯一视图计数排序
     • 在指定时间段内按视图计数排序
     • 在指定集合内按视图计数排序
   • 获取可查看类型的视图计数
   • 查看集合
   • 在删除时移除视图
   • 缓存视图计数
3. 优化
   • 基准测试
   • 数据库索引
   • 缓存
4. 扩展
   • 自定义访客信息
   • 使用您自己的Views Eloquent模型
   • 使用您自己的View Eloquent模型
   • 使用自定义爬虫检测器
   • 向Views类添加宏

入门

要求

本包需要 PHP 7.4+ 和 Laravel 6+。

不维护 Lumen 的支持！

版本信息

安装

首先，您需要通过 Composer 安装此包

composer require cyrildewit/eloquent-viewable

其次，您可以使用以下命令发布迁移

php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="migrations"

最后，您需要运行 migrate 命令

php artisan migrate

您可以选择使用以下命令发布配置文件

php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="config"

手动注册服务提供者

如果您更喜欢手动注册包，您可以将以下提供者添加到您应用程序的提供者列表中。

// config/app.php

'providers' => [
    // ...
    CyrildeWit\EloquentViewable\EloquentViewableServiceProvider::class,
];

使用方法

准备您的模型

要将视图与模型关联，该模型 必须 实现以下接口和特质

• 接口： CyrildeWit\EloquentViewable\Contracts\Viewable
• 特质： CyrildeWit\EloquentViewable\InteractsWithViews

示例

use Illuminate\Database\Eloquent\Model;
use CyrildeWit\EloquentViewable\InteractsWithViews;
use CyrildeWit\EloquentViewable\Contracts\Viewable;

class Post extends Model implements Viewable
{
    use InteractsWithViews;

    // ...
}

记录视图

要记录视图，您可以在流畅的 Views 实例上调用 record 方法。

views($post)->record();

记录访客的视图的最佳位置是在您的控制器内部。例如

// PostController.php
public function show(Post $post)
{
    views($post)->record();

    return view('post.show', compact('post'));
}

注意： 此包默认会过滤掉爬虫。在测试时请注意这一点，因为 Postman 例如也是一个爬虫。

设置冷却时间

您可以在 Views 实例上使用 cooldown 方法来在视图记录之间添加冷却时间。设置冷却时间时，您需要指定分钟数。

views($post)
    ->cooldown($minutes)
    ->record();

您也可以传递一个 DateTimeInterface 实例，而不是传递分钟数的整数。

$expiresAt = now()->addHours(3);

views($post)
    ->cooldown($expiresAt)
    ->record();

它的工作原理

当使用会话延迟记录视图时，此包还会将视图的快照保存到访客的会话中，并带有过期日期时间。每次访客再次查看项目时，此包都会检查其会话，并决定是否将视图保存到数据库中。

检索查看次数

获取总查看次数

views($post)->count();

获取特定期间的观点次数

use CyrildeWit\EloquentViewable\Support\Period;

// Example: get views count from 2017 upto 2018
views($post)
    ->period(Period::create('2017', '2018'))
    ->count();

此包附带的一个 Period 类提供了许多实用的功能。该类的 API 如下所示

在两个日期时间之间

$startDateTime = Carbon::createFromDate(2017, 4, 12);
$endDateTime = '2017-06-12';

Period::create($startDateTime, $endDateTime);

自一个日期时间以来

Period::since(Carbon::create(2017));

至一个日期时间

Period::upto(Carbon::createFromDate(2018, 6, 1));

过去以来

使用 Carbon::today() 作为起始日期时间，减去给定的单位。

Period::pastDays(int $days);
Period::pastWeeks(int $weeks);
Period::pastMonths(int $months);
Period::pastYears(int $years);

自从子

使用 Carbon::now() 作为起始日期时间，减去给定的单位。

Period::subSeconds(int $seconds);
Period::subMinutes(int $minutes);
Period::subHours(int $hours);
Period::subDays(int $days);
Period::subWeeks(int $weeks);
Period::subMonths(int $months);
Period::subYears(int $years);

获取总独立观看次数

如果您只想检索独立观看次数，可以直接在链中添加 unique 方法。

views($post)
    ->unique()
    ->count();

按观看次数排序模型

Viewable 特性为您的模型添加了两个作用域：orderByViews 和 orderByUniqueViews。

按观看次数排序

Post::orderByViews()->get(); // descending
Post::orderByViews('asc')->get(); // ascending

按独立观看次数排序

Post::orderByUniqueViews()->get(); // descending
Post::orderByUniqueViews('asc')->get(); // ascending

在指定时间段内按观看次数排序

Post::orderByViews('asc', Period::pastDays(3))->get();  // descending
Post::orderByViews('desc', Period::pastDays(3))->get(); // ascending

当然，也可以使用独立观看次数变体

Post::orderByUniqueViews('asc', Period::pastDays(3))->get();  // descending
Post::orderByUniqueViews('desc', Period::pastDays(3))->get(); // ascending

在指定集合内按观看次数排序

Post::orderByViews('asc', null, 'custom-collection')->get();  // descending
Post::orderByViews('desc', null, 'custom-collection')->get(); // ascending

Post::orderByUniqueViews('asc', null, 'custom-collection')->get();  // descending
Post::orderByUniqueViews('desc', null, 'custom-collection')->get(); // ascending

获取可观看类型的观看次数

如果您想了解特定可观看类型有多少次观看，需要像这样将空的 Eloquent 模型传递给 views() 辅助函数

views(new Post())->count();

您也可以传递一个完全限定的类名。然后包将从这个应用程序容器中解析一个实例。

views(Post::class)->count();
views('App\Post')->count();

查看集合

如果您有相同可观看类型的不同类型观看，您可能希望将它们存储在自己的集合中。

views($post)
    ->collection('customCollection')
    ->record();

要检索特定集合中的观看次数，可以重复使用相同的 collection() 方法。

views($post)
    ->collection('customCollection')
    ->count();

删除时移除观看次数

要自动删除可观看 Eloquent 模型的所有观看次数，可以在模型定义中将 removeViewsOnDelete 属性设置为 true。

protected $removeViewsOnDelete = true;

缓存观看次数

在某些场景中，缓存观看次数可能具有挑战性。例如，周期可能是动态的，这使得缓存变得不可能。这就是为什么您可以使用内置的缓存功能。

要缓存观看次数，只需将 remember() 方法添加到链中。默认生存期是永久的。

示例

views($post)->remember()->count();
views($post)->period(Period::create('2018-01-24', '2018-05-22'))->remember()->count();
views($post)->period(Period::upto('2018-11-10'))->unique()->remember()->count();
views($post)->period(Period::pastMonths(2))->remember()->count();
views($post)->period(Period::subHours(6))->remember()->count();

// Cache for 3600 seconds
views($post)->remember(3600)->count();

// Cache until the defined DateTime
views($post)->remember(now()->addWeeks(2))->count();

// Cache forever
views($post)->remember()->count();

优化

基准测试

数据库索引

默认的 views 表迁移文件已经为 viewable_id 和 viewable_type 添加了两个索引。

如果您有足够的存储空间，可以添加另一个索引到 visitor 列。根据观看次数的数量，这可能在某些情况下加快查询速度。

缓存

缓存视图计数会对您应用程序的性能产生重大影响。您可以在此处阅读有关缓存视图计数的文档 这里

使用 remember() 方法将只缓存由 count() 方法生成的视图计数。orderByViews 和 orderByUnique 查询范围不使用这些值，因为它们只是向查询构建器添加了一些内容。为了优化这些查询，您可以在可查看的数据库表中添加额外的列或多列来存储这些计数。

示例：我们想按 独立视图 计数对博客文章进行排序。您可能首先想到的是使用 orderByUniqueViews 查询范围。

$posts = Post::latest()->orderByUniqueViews()->paginate(20);

当您存储了大量的视图时，此查询相当慢。为了加快速度，您可以在 posts 表中添加例如 unique_views_count 列。我们需要定期更新此列的独立视图计数。这可以通过计划任务 Laravel 命令轻松实现。

可能还有更快的方法来完成此操作，但这样的命令可能如下所示

$posts = Post::all();

foreach($posts as $post) {
    $post->unique_views_count = views($post)->unique()->count();
}

待更新！Laravel 有一个很好的块和游标功能，这可能很有用。

扩展

如果您想用自己的实现扩展或替换核心类，您可以通过覆盖它们来实现

• CyrildeWit\EloquentViewable\Views
• CyrildeWit\EloquentViewable\View
• CyrildeWit\EloquentViewable\Visitor
• CyrildeWit\EloquentViewable\CrawlerDetectAdapter

注意：不要忘记，所有自定义类都必须实现其原始接口

关于访客的定制信息

Visitor 类负责为 Views 构建器提供有关当前访客的信息。以下信息提供：

• 一个唯一的标识符（存储在cookie中）
• IP地址
• 检查Do Not Track标题
• 检查爬虫

默认的 Visitor 类从请求中获取其信息。因此，当您通过RESTful API使用 Views 构建器时，您可能会遇到一些问题。为了解决这个问题，您需要提供有关访客的自己的数据。

您可以在全局或局部覆盖 Visitor 类。

创建自己的 Visitor 类

在您的 Laravel 应用程序中创建自己的 Visitor 类，并实现 CyrildeWit\EloquentViewable\Contracts\Visitor 接口。创建接口所需的方法。

或者，您可以扩展此包附带默认的 Visitor 类。

全局

只需将您的自定义 Visitor 实现绑定到 CyrildeWit\EloquentViewable\Contracts\Visitor 合同。

$this->app->bind(
    \CyrildeWit\EloquentViewable\Contracts\Visitor::class,
    \App\Services\Views\Visitor::class
);

局部

您还可以使用 Views 构建器上的 useVisitor 设置器方法设置访客实例。

use App\Services\Views\Visitor;

views($post)
    ->useVisitor(new Visitor()) // or app(Visitor::class)
    ->record();

使用您自己的 Views Eloquent 模型

将您的自定义 Views 实现绑定到 \CyrildeWit\EloquentViewable\Contracts\Views。

更改以下代码片段，并将其放置在服务提供商（例如 AppServiceProvider）的 register 方法中。

$this->app->bind(
    \CyrildeWit\EloquentViewable\Contracts\Views::class,
    \App\Services\Views\Views::class
);

使用自己的 View Eloquent 模型

将您的自定义 View 实现绑定到 \CyrildeWit\EloquentViewable\Contracts\View。

更改以下代码片段，并将其放置在服务提供商（例如 AppServiceProvider）的 register 方法中。

$this->app->bind(
    \CyrildeWit\EloquentViewable\Contracts\View::class,
    \App\Models\View::class
);

使用自定义爬虫检测器

将您的自定义 CrawlerDetector 实现绑定到 \CyrildeWit\EloquentViewable\Contracts\CrawlerDetector。

更改以下代码片段，并将其放置在服务提供商（例如 AppServiceProvider）的 register 方法中。

$this->app->singleton(
    \CyrildeWit\EloquentViewable\Contracts\CrawlerDetector::class,
    \App\Services\Views\CustomCrawlerDetectorAdapter::class
);

向 Views 类添加宏

use CyrildeWit\EloquentViewable\Views;

Views::macro('countAndRemember', function () {
    return $this->remember()->count();
});

现在您可以使用这个简写方法，如下所示

views($post)->countAndRemember();

Views::forViewable($post)->countAndRemember();

升级

请参阅 UPGRADING 了解详细的升级指南。

变更日志

请参阅 CHANGELOG 了解最近的变化。

贡献

请参阅 CONTRIBUTING 了解详细信息。

鸣谢

• Cyril de Wit - 初始工作 - cyrildewit

请参阅参与此项目的贡献者列表。

有用的资源

• 在 Laravel 中实现页面浏览计数器 - Stidges

替代方案

• antonioribeiro/tracker
• foothing/laravel-simple-pageviews
• awssat/laravel-visits
• Kryptonit3/Counter
• fraank/ViewCounter

欢迎添加更多替代方案！

许可

本项目采用 MIT 许可协议 - 请参阅 LICENSE 文件了解详细信息。