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类提供许多实用的功能。以下是如何使用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

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

如果您想知道特定可观看类型有多少观看次数，您需要像这样向 views() 助手传递一个空的 Eloquent 模型

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文件以获取详细信息。