README

注意：这是一个不稳定分支！

这个Laravel >= 5.5的包允许你将视图与Eloquent模型关联。

安装后，你可以做如下操作

// Get the total number of views
$post->getViews();

// Get the total number of views since the given date
$post->getViews(Period::since(Carbon::parse('2014-02-23 00:00:00')));

// Get the total number of views between the given date range
$post->getViews(Period::create(Carbon::parse('2014-00-00 00:00:00'), Carbon::parse('2016-00-00 00:00:00')));

// Get the total number of views in the past 6 weeks (from today)
$post->getViews(Period::pastWeeks(6));

// Get the total number of views in the past 2 hours (from now)
$post->getViews(Period::subHours(2));

// Store a new view in the database
$post->addView();

概述

Eloquent Viewable是一个灵活且易于使用的Laravel包，可以将视图与Eloquent模型关联。它适用于大型和小型项目。与简单的计数器不同，这个包会提供完整的视图历史记录。

此包不是为了收集分析数据而构建的。它用于简单地存储Laravel Eloquent模型的视图。你可以将此包用于Post、Video、Course和Hotel等模型，当然，你也可以按需使用此包。

特性

以下是主要特性

• 将视图与Eloquent模型关联
• 获取（唯一）视图总数
• 获取自特定日期以来的（唯一）视图总数
• 获取到特定日期的（唯一）视图总数
• 获取两个日期之间的（唯一）视图总数
• 获取从今天起的过去days、weeks、months和years的（唯一）视图总数
• 获取从现在起的过去seconds、minutes、hours、days、weeks、months和years的（唯一）视图总数
• 缓存检索到的视图计数
• 在数据库中保存之前将视图排队，以防止慢请求

非常欢迎功能请求！创建以[Feature Request]为前缀的问题或发送pull request。

文档

在此文档中，你可以找到有关使用此Laravel包的一些有用信息。

目录

1. 入门
   • 要求
   • 安装
2. 使用
   • 准备你的模型
   • 存储视图
   • 带有过期日期的存储视图
   • 按标签存储视图
   • 检索视图计数
   • 按视图计数排序模型
   • Views助手
3. 配置
   • 排队ProcessView作业
   • 扩展
4. 食谱
   • 为常用周期格式创建辅助方法

入门

要求

Eloquent Viewable包需要PHP 7+和Laravel 5.5+。

Lumen不受支持！

版本信息

feature/tags | 1.0 | 5.5 - 5.6 | 仅修复bug | >= 7.0.0 |

安装

您可以通过composer安装此包

composer require cyrildewit/eloquent-viewable

可选，您可以在config/app.php文件中添加服务提供者。否则，可以通过自动包发现完成。

// config/app.php

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

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

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

发布迁移文件后，您可以通过运行迁移来创建views表。但是，如果您已经有一个名为views的表，您可以在配置中更改此名称。搜索'models->view->table_name'并更改值以使其唯一。

php artisan migrate

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

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

使用

在以下部分中，您将找到有关使用此包的信息。

准备你的模型

要使Eloquent模型可查看，只需将Viewable特质添加到模型定义中。此特质提供各种方法，允许您保存视图、检索视图计数并按视图计数排序项。

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

class Post extends Model
{
    use Viewable;

    // ...
}

存储视图

通过在可查看模型上调用 ->addView() 方法，轻松将新视图添加到模型中。

最佳放置位置是在控制器内部。如果您遵循 CRUD 标准，则应该是 @show 方法。

$post->addView();

一个 PostController 可能看起来像这样

// ...
public function show(Post $post)
{
    $post->addView();

    return view('blog.post', compact('post'));
}
// ...

注意：如果您想排队此作业，可以在配置中开启！请参阅排队 ProcessView 作业部分！

带有过期日期的存储视图

如果您想在同一会话中的视图之间添加延迟，可以使用可查看模型上的 addViewWithExpiryDate。

$post->addViewWithExpiryDate(Carbon::now()->addHours(2));

此方法将向您的模型添加新视图，并在用户的会话中添加一条记录。如果您多次调用此方法，您会看到视图计数不会增加。当前日期时间超过到期日期后，将存储新的视图。

按标签存储视图

在某些情况下，您可能希望为可查看模型设置多个计数器。通过向 addView 方法传递额外的参数可以轻松实现。

$post->addView('customTag');

并带有到期日期

$post->addViewWithExpiryDate(Carbon::now()->addHours(2), 'customTag')

检索视图计数

将 Viewable 特性添加到您的模型后，您将能够在可查看模型上调用 getViews() 和 getUniqueViews()。两种方法都接受一个可选的 Period 实例。

/**
 * Get the total number of views.
 *
 * @param  \CyrildeWit\EloquentViewable\Support\Period
 * @return int
 */
public function getViews($period = null): int;

/**
 * Get the total number of unique views.
 *
 * @param  \CyrildeWit\EloquentViewable\Support\Period
 * @return int
 */
public function getUniqueViews($period = null) : int;

Period 类

请注意，以下代码不是有效的 PHP 语法！

// Create a new Period instance.
Period::create(DateTime $startDateTime = null, DateTime $endDateTime = null);

// Create a new Period instance with only a start date time.
Period::since(DateTime $startDateTime);

// Create a new Period instance with only a end date time.
Period::upto(DateTime $endDateTime);

// Period instance with a start date time of today minus the given days.
Period::pastDays(int $days);

// Period instance with a start date time of today minus the given weeks.
Period::pastWeeks(int $weeks);

// Period instance with a start date time of today minus the given months.
Period::pastMonths(int $months);

// Period instance with a start date time of today minus the given years.
Period::pastYears(int $years);

// Period instance with a start date time of now minus the given seconds.
Period::subSeconds(int $seconds);

//Period instance with a start date time of now minus the given minutes.
Period::subMinutes(int $minutes);

// Period instance with a start date time of now minus the given hours.
Period::subHours(int $hours);

// Period instance with a start date time of now minus the given days.
Period::subDays(int $days);

// Period instance with a start date time of now minus the given weeks.
Period::subWeeks(int $weeks);

// Period instance with a start date time of now minus the given months.
Period::subMonths(int $months);

// Period instance with a start date time of now minus the given years.
Period::subYears(int $years);

示例

$post->getViews();

$post->getViews(Period::since(Carbon::parse('2007-05-21 12:23:00')));

$post->getViews(Period::upto(Carbon::parse('2013-05-21 00:00:00')));

$post->getViews(Period::create(Carbon::parse('2014-00-00 00:00:00'), Carbon::parse('2016-00-00 00:00:00')));

$post->getUniqueViews();

$post->getUniqueViews(Period::since(Carbon::parse('2007-05-21 12:23:00')));

$post->getUniqueViews(Period::upto(Carbon::parse('2013-05-21 00:00:00')));

$post->getUniqueViews(Period::create(Carbon::parse('2014-00-00 00:00:00'), Carbon::parse('2016-00-00 00:00:00')));

$post->getViews(Period::pastDays(5));

$post->getViews(Period::pastWeeks(6));

$post->getViews(Period::pastMonths(8));

$post->getViews(Period::pastYears(3));

$post->getUniqueViews(Period::pastDays(5));

$post->getUniqueViews(Period::pastWeeks(6));

$post->getUniqueViews(Period::pastMonths(8));

$post->getUniqueViews(Period::pastYears(3));

$post->getViews(Period::subSeconds(30));

$post->getViews(Period::subMinutes(15));

$post->getViews(Period::subHours(8));

$post->getViews(Period::subDays(5));

$post->getViews(Period::subWeeks(6));

$post->getViews(Period::subMonths(8));

$post->getViews(Period::subYears(3));

$post->getUniqueViews(Period::subSeconds(30));

$post->getUniqueViews(Period::subMinutes(15));

$post->getUniqueViews(Period::subHours(8));

$post->getUniqueViews(Period::subDays(5));

$post->getUniqueViews(Period::subWeeks(6));

$post->getUniqueViews(Period::subMonths(8));

$post->getUniqueViews(Period::subYears(3));

按视图计数排序模型

按视图数量检索可查看模型

$sortedPosts = Post::orderByViewsCount()->get(); // desc
$sortedPosts = Post::orderByViewsCount('asc')->get();

按唯一视图数量检索可查看模型

$sortedPosts = Post::orderByUniqueViewsCount()->get(); // desc
$sortedPosts = Post::orderByUniqueViewsCount('asc')->get();

Views助手

保存视图

use CyrildeWit\EloquentViewable\Views;

Views::create($post)->addView();

带到期日期保存视图

use CyrildeWit\EloquentViewable\Views;

Views::create($post)->addViewWithExpiryDate(Carbon::now()->addHours(2));

按标签保存视图

use CyrildeWit\EloquentViewable\Views;

// addView method
Views::create($post)->addView('customTag');

// addViewWithExpiryDate method
Views::create($post)->addViewWithExpiryDate(Carbon::now()->addHours(2), 'customTag');

检索视图计数

use CyrildeWit\EloquentViewable\Views;

Views::create($post)->getViews();

按可查看类型获取视图

要获取某个可查看类型的总视图数，您可以使用以下方法之一。

use CyrildeWit\EloquentViewable\Views;

Views::getViewsByType($post);
Views::getViewsByType(Post::class);
Views::getViewsByType('App\Post');

按类型获取最受欢迎的可查看对象

use CyrildeWit\EloquentViewable\Views;

// Get top 10 most viewed by type
Views::getMostViewedByType($post, 10);
Views::getMostViewedByType(Post::class, 10);
Views::getMostViewedByType('App\Post', 10);

// Get top 10 lowest viewed by type
Views::getLowestViewedByType($post, 10);
Views::getLowestViewedByType(Post::class, 10);
Views::getLowestViewedByType('App\Post', 10);

按周期获取可查看对象的视图计数

不要将此方法与 Period 类混淆！

use CyrildeWit\EloquentViewable\Views;

Views::getViewsPerPeriod('minute', 30); // per 30 minutes
Views::getViewsPerPeriod('hour', 12); // per 12 hours
Views::getViewsPerPeriod('day'); // per day
Views::getViewsPerPeriod('week', 2); // per 2 weeks
Views::getViewsPerPeriod('month'); // per month
Views::getViewsPerPeriod('year'); // per month

配置

排队ProcessView作业

当在您的模型上调用 ->addView() 方法时，它将在数据库中保存新的视图和一些数据。因为这样可以减慢您的应用程序，所以您可以通过更改配置文件中 jobs 下的 store_new_view 的值来开启队列。确保您的应用程序已准备好排队。如果不是，请参阅官方的Laravel 文档以获取更多信息！

扩展

如果您想用您自己的实现扩展或替换其中一个核心类，您可以使用它们

• CyrildeWit\EloquentViewable\View
• CyrildeWit\EloquentViewable\ViewableService
• CyrildeWit\EloquentViewable\CrawlerDetector\CrawlerDetectAdapter

注意：请记住，所有自定义类都必须实现它们原始的接口

用自定义实现替换 View 模型

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

用自定义实现替换 ViewableService 服务

$this->app->singleton(
    \CyrildeWit\EloquentViewable\Contracts\ViewableService::class,
    \App\Services\CustomViewableService::class
);

用自定义实现替换 CrawlerDetectAdapter 类

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

食谱

为常用周期格式创建辅助方法

App\Models\Post

// ...

public function getViewsSince(DateTime $sinceDateTime)
{
    return $this->getViews(Period::since($sinceDateTime));
}

public function getViewsUpto(DateTime $uptoDateTime)
{
    return $this->getViews(Period::upto($uptoDateTime));
}

public function getViewsBetween(DateTime $sinceDateTime, DateTime $uptoDateTime)
{
    return $this->getViews(Period::create($sinceDateTime, $uptoDateTime));
}

public function getViewsInPastDays(int $days)
{
    return $this->getViews(Period::pastDays($days));
}

// ...

resources/views/post/show.blade.php

<!-- ... -->

Page views since 2014: {{ $post->getViewsSince(Carbon::create(2014)) }}
Page views upto 2016: {{ $post->getViewsUpto(Carbon::create(2016)) }}
Page views between 2016 - 2018: {{ $post->getViewsBetween(Carbon::create(2016), Carbon::create(2018)) }}

Page views in the past 5 days: {{ $post->getViewsInPastDays(5) }}

<!-- ... -->

升级

请参阅UPGRADING以获取详细的升级指南。

变更日志

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

贡献

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

致谢

• Cyril de Wit
• 所有贡献者

许可

本项目采用 MIT 许可证 - 请参阅 LICENSE.md 文件以获取详细信息。