lcoy / recommendations
A Flarum extension that adds a three-column recommendation widget (Recommended, Latest, Most Viewed) powered by FoF Forum Widgets Core
Maintainers
Package info
gitee.com/lcoy/flarum-recommendations
Type:flarum-extension
pkg:composer/lcoy/recommendations
Requires
- php: ^8.1
- flarum/core: ^2.0
- fof/forum-widgets-core: ^2.0
Requires (Dev)
Suggests
- fof/discussion-views: Required for Most Viewed ranking by view count. Without it, view_count will always be 0.
- fof/redis: Redis cache driver for better caching performance. Falls back to file cache if not installed.
This package is not auto-updated.
Last update: 2026-06-04 03:48:29 UTC
README
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 — Time-window filtered, low-engagement posts to surface undiscovered content
- 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
| Package | Type | Notes |
|---|---|---|
flarum/core | Required | ^2.0 |
fof/forum-widgets-core | Required | ^2.0 |
fof/discussion-views | Recommended | Provides view_count data. Without it, Most Viewed column has no data to rank |
| Redis cache | Recommended | Better caching performance. Falls back to file cache |
Installation
composer require lcoy/recommendations
php flarum cache:clear
For view tracking support:
composer require fof/discussion-views
Admin Settings
8 configurable parameters under Admin → Forum Widgets → Recommendations:
| Setting | Default | Description |
|---|---|---|
| Recommended Count | 5 | Items shown in Recommended column |
| Gravity Factor | 1.5 | Time-decay strength (higher = newer posts favored) |
| Latest Count | 5 | Items shown in Latest column |
| Time Window (days) | 7 | Only show posts within this many days |
| Max Participants | 5 | Only show posts with unique participants ≤ this |
| Most Viewed Count | 5 | Items shown in Most Viewed column |
| Min View Threshold | 0 | Minimum views to enter candidate pool (0 = no limit) |
| Cache TTL (minutes) | 15 | Frontend polling & backend cache interval (0 = disabled) |
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
- Fetch top 200 candidates from the last 90 days
- Rank by hotness score
- Take top N×10 as the random pool
- Shuffle and pick N items
Most Viewed (Threshold + Randomization)
- Fetch top N×10 by view count (with optional min-views filter)
- Shuffle and pick N items
Tech Stack
- Backend: PHP 8.1+, 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 热度算法 + 随机选取，兼顾质量与多样性
- 最新帖子 — 时间窗口 + 低互动过滤，挖掘尚待发现的新内容
- 热门浏览 — 浏览量门槛 + 随机选取，确保热门内容不重复
每个栏目项展示：头像 + 标题 + 元数据（评论数 / 发布时间 / 浏览数），点击可跳转到帖子详情。
依赖
| 扩展 | 必要性 | 说明 |
|---|---|---|
flarum/core | 必需 | ^2.0 |
fof/forum-widgets-core | 必需 | ^2.0 |
fof/discussion-views | 推荐 | 提供浏览量数据，未安装时热门栏目无区分度 |
| Redis 缓存 | 推荐 | 更好的缓存性能，未配置时回退到文件缓存 |
安装
composer require lcoy/recommendations
php flarum cache:clear
推荐同时安装浏览量追踪扩展：
composer require fof/discussion-views
后台设置
8 项可配置参数，位于 后台 → 论坛小组件 → Recommendations：
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 推荐帖子展示数量 | 5 | 推荐栏目展示条数 |
| 重力因子 | 1.5 | 热度算法时间衰减强度，值越大新帖权重越高 |
| 最新帖子展示数量 | 5 | 最新栏目展示条数 |
| 时间窗口（天） | 7 | 仅展示此天数内发布的帖子 |
| 最大参与人数 | 5 | 仅展示参与者 ≤ 此值的帖子 |
| 热门浏览展示数量 | 5 | 热门栏目展示条数 |
| 热门浏览最低门槛 | 0 | 浏览量需 ≥ 此值才进入候选池，0 不设限 |
| 数据刷新间隔（分钟） | 15 | 前端轮询与后端缓存时长，0 关闭缓存 |
算法详解
推荐算法（热度 + 随机化）
engagement = 评论数 × 2.0 + 参与人数 × 3.0 + 浏览量 × 0.05
hours = max(1, 距发布小时数)
score = engagement / (hours + 2)^gravity
- 从近 90 天帖子中取 200 条候选
- 按热度分降序排列
- 取前 N×10 条组成随机池
- shuffle 后选取前 N 条
热门浏览随机化
- 按浏览量降序取前 N×10 条（可设最低门槛过滤）
- shuffle 后取前 N 条
技术架构
lcoy/recommendations
├── src/
│ ├── Api/Controller/
│ │ └── ListRecommendationsController.php # API 控制器
│ └── Service/
│ └── HotnessCalculator.php # 热度算法
├── js/
│ ├── dist/ # 构建产物（已提交）
│ └── src/
│ ├── admin/
│ │ └── extendSettingsPage.js # 后台设置注册
│ └── common/
│ ├── components/
│ │ ├── RecommendationsWidget.js # 前台小部件
│ │ └── RecommendationsWidgetAdmin.js # 后台小部件注册
│ └── registerWidget.js # 小部件注册
├── less/
│ └── forum.less # 前台样式（含移动端适配）
├── locale/
│ ├── zh.yml # 中文翻译
│ └── en.yml # 英文翻译
├── extend.php # 扩展入口
└── composer.json
许可证
MIT