README

中文文档 | English

English

A Flarum 2.0 extension that adds a three-column recommendation widget to the forum homepage, built on the FoF Forum Widgets Core framework.

Features

• Recommended — HN/Reddit hotness algorithm with stochastic sampling for diversity
• Latest — Purely ordered by creation time descending
• Most Viewed — View-count ranked with configurable threshold and randomization

Each item displays: avatar + title + metadata (comments / time / views). Clickable to the discussion page.

Requirements

Installation

composer require lcoy/recommendations
php flarum migrate
php flarum cache:clear

For view tracking support:

composer require fof/discussion-views

Admin Settings

6 configurable parameters under Admin → Forum Widgets → Recommendations:

Algorithm

Recommended (Hotness + Randomization)

engagement = comments × 2.0 + participants × 3.0 + views × 0.05
hours      = max(1, hours since creation)
score      = engagement / (hours + 2)^gravity

1. Fetch top 80 candidates from the last 60 days
2. Rank by hotness score
3. Take top N×3 as the random pool
4. Shuffle and pick N items

Most Viewed (Threshold + Randomization)

1. Fetch top N×3 by view count (with optional min-views filter)
2. Shuffle and pick N items

Tech Stack

• Backend: PHP 8.3+, Laravel Cache (Redis recommended)
• Frontend: Mithril.js, Flarum Admin Extender API
• Widget framework: FoF Forum Widgets Core

License

MIT

中文说明

基于 FoF Forum Widgets Core 框架构建的 Flarum 2.0 推荐系统扩展，在论坛首页以三栏小部件形式展示推荐帖子、最新帖子和热门浏览帖子。

功能

• 推荐帖子 — HN/Reddit 热度算法 + 随机选取，兼顾质量与多样性
• 最新帖子 — 纯粹按发布时间倒序排列
• 热门浏览 — 浏览量门槛 + 随机选取，确保热门内容不重复

每个栏目项展示：头像 + 标题 + 元数据（评论数 / 发布时间 / 浏览数），点击可跳转到帖子详情。

依赖

安装

composer require lcoy/recommendations
php flarum migrate
php flarum cache:clear

推荐同时安装浏览量追踪扩展：

composer require fof/discussion-views

后台设置

6 项可配置参数，位于 后台 → 论坛小组件 → Recommendations：

算法详解

推荐算法（热度 + 随机化）

engagement = 评论数 × 2.0 + 参与人数 × 3.0 + 浏览量 × 0.05
hours      = max(1, 距发布小时数)
score      = engagement / (hours + 2)^gravity

1. 从近 60 天帖子中取 80 条候选
2. 按热度分降序排列
3. 取前 N×3 条组成随机池
4. shuffle 后选取前 N 条

热门浏览随机化

1. 按浏览量降序取前 N×3 条（可设最低门槛过滤）
2. shuffle 后取前 N 条

技术架构

lcoy/recommendations
├── src/
│   ├── Api/Controller/
│   │   └── ListRecommendationsController.php  # API 控制器
│   └── Service/
│       └── HotnessCalculator.php              # 热度算法
├── js/
│   ├── dist/                                  # 构建产物（已提交）
│   └── src/
│       ├── admin/
│       │   ├── components/
│       │   │   └── RecommendationsWidgetAdmin.js  # 后台小部件占位组件
│       │   └── extendSettingsPage.js              # 后台设置注册
│       ├── forum/
│       │   └── components/
│       │       └── RecommendationsWidget.js       # 前台小部件
│       └── common/
│           └── registerWidget.js                  # 小部件注册（前后台共用）
├── less/
│   └── forum.less                            # 前台样式（含移动端适配）
├── migrations/
│   └── ..._add_view_count_index_to_discussions.php  # 热门栏目排序索引
├── locale/
│   ├── zh.yml                                # 中文翻译
│   └── en.yml                                # 英文翻译
├── tests/
│   └── Unit/
│       └── HotnessCalculatorTest.php         # 热度算法性质测试
├── extend.php                                # 扩展入口
├── phpunit.xml.dist                          # 测试配置
└── composer.json

开发

composer test          # 运行单元测试
composer analyse:php   # 静态分析（需先安装 require-dev 依赖）

可见性说明

三个栏目对所有用户共用同一份缓存，因此内容一律按访客视角构建（whereVisibleTo(Guest)）， 自动复用 Flarum 及各扩展注册的可见性作用域：

• 私密帖子、已隐藏帖子、零回复帖子（核心作用域）
• 受限标签内的帖子、未审核通过的帖子（flarum/tags、flarum/approval 等扩展作用域）

这保证了受限内容不会因缓存共享而泄露给访客。副作用是：登录用户也不会在小部件中看到 上述受限内容——这是共享缓存的必要取舍。

缓存失效

三个栏目默认缓存 15 分钟（可在后台调整），以下事件会立即清除缓存：

「推荐」与「热门浏览」按设计依赖缓存过期后重新随机抽取，因此不会随新帖即时变化。

许可证

MIT