lcoy / recommendations
A Flarum extension that adds a three-column recommendation widget (Recommended, Latest, Most Viewed) powered by FoF Forum Widgets Core
Package info
gitee.com/lcoy/flarum-recommendations
Type:flarum-extension
pkg:composer/lcoy/recommendations
Requires
- php: ^8.3
- flarum/core: ^2.0
- fof/forum-widgets-core: ^2.0
Requires (Dev)
- flarum/phpstan: *
- phpunit/phpunit: ^12.5
Suggests
- fof/discussion-views: Provides the view_count column for the Most Viewed ranking. Without it, that column falls back to creation time and the view threshold setting is ignored.
- fof/redis: Redis cache driver for better caching performance. Falls back to file cache if not installed.
Provides
None
Conflicts
None
Replaces
None
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 — 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
| Package | Type | Notes |
|---|---|---|
flarum/core | Required | ^2.0 — verified on Flarum 2.0.1 (2.0 stable) |
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 |
| Queue worker / cron | Optional | Only needed for off-request cache warm-up; the widget works without them |
Installation
composer require lcoy/recommendations
php flarum migrate
php flarum cache:clear
For view tracking support:
composer require fof/discussion-views
Upgrading Flarum? Run
php flarum cache:clearafter a core upgrade. Flarum caches a compiled formatter that is bound to the core version; a stale entry can cause500errors on every page until it is rebuilt.
Admin Settings
10 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) |
| Candidate Window (days) | 60 | Only discussions created within this window can be recommended |
| Latest Count | 5 | Items shown in Latest column |
| 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 | Base cache duration (0 = disabled) |
| Recommended TTL (minutes) | 0 | Per-column override; 0 follows the base duration |
| Latest TTL (minutes) | 0 | Per-column override; 0 follows the base duration |
| Most Viewed TTL (minutes) | 0 | Per-column override; 0 follows the base duration |
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 80 candidates within the candidate window (60 days by default)
- Rank by hotness score
- Take top N×3 as the random pool
- Shuffle and pick N items
Most Viewed (Threshold + Randomization)
- Fetch top N×3 by view count (with optional min-views filter)
- Shuffle and pick N items
Caching & Warm-up
Three cache keys, one per column: lcoy-recommendations:v2:{recommended,latest,most_viewed}.
Each column's TTL resolves as: per-column setting → base cache_ttl → 0 (disabled).
| Event | Invalidated |
|---|---|
| New discussion posted | Latest only |
| Title renamed | All columns |
| Discussion hidden / deleted / restored | All columns |
Any lcoy-recommendations.* setting saved | All columns |
Invalidation is immediate, then a warm-up job refills the columns in the background. A warm-up only builds columns whose key is missing, so each column's TTL stays authoritative rather than being reset by the warm-up interval:
php flarum recommendations:warm # queue a warm-up job (fills missing columns)
php flarum recommendations:warm --sync # rebuild in this process, even if cached
php flarum schedule:run # required for the 15-minute schedule
Warm-up is optional. Without a queue worker the job runs inline on the write request that triggered it; if nothing runs at all, the first read after expiry rebuilds synchronously (about 15 ms) and the widget renders normally. With caching disabled or the cache backend unavailable, every request falls back to a direct build — no errors, no blank widget.
Tech Stack
- Backend: PHP 8.3+, Laravel Cache (Redis recommended), Flarum queue
- 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 —— 已在 Flarum 2.0.1(2.0 正式版)验证 |
fof/forum-widgets-core | 必需 | ^2.0 |
fof/discussion-views | 推荐 | 提供 view_count 列供热门栏目排序。未安装时该栏目退化为按发布时间排序,浏览量门槛设置不生效 |
| Redis 缓存 | 推荐 | 更好的缓存性能,未配置时回退到文件缓存 |
| 队列 worker / 定时任务 | 可选 | 仅用于把缓存预热挪出请求;不配置也能正常工作 |
安装
composer require lcoy/recommendations
php flarum migrate
php flarum cache:clear
推荐同时安装浏览量追踪扩展:
composer require fof/discussion-views
升级 Flarum 核心后请执行
php flarum cache:clear。Flarum 会缓存与核心版本绑定的已编译 formatter,残留的旧缓存会导致所有页面 500,清除后方能重建。
后台设置
10 项可配置参数,位于 后台 → 论坛小组件 → Recommendations:
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 推荐帖子展示数量 | 5 | 推荐栏目展示条数 |
| 重力因子 | 1.5 | 热度算法时间衰减强度,值越大新帖权重越高 |
| 推荐候选时间窗口(天) | 60 | 仅此时间范围内创建的帖子可进入推荐候选 |
| 最新帖子展示数量 | 5 | 最新栏目展示条数 |
| 热门浏览展示数量 | 5 | 热门栏目展示条数 |
| 热门浏览最低门槛 | 0 | 浏览量需 ≥ 此值才进入候选池,0 不设限 |
| 缓存时长(分钟) | 15 | 基础缓存时长,0 关闭缓存 |
| 推荐栏目缓存时长(分钟) | 0 | 栏目级覆盖,0 跟随基础时长 |
| 最新栏目缓存时长(分钟) | 0 | 栏目级覆盖,0 跟随基础时长 |
| 热门栏目缓存时长(分钟) | 0 | 栏目级覆盖,0 跟随基础时长 |
算法详解
推荐算法(热度 + 随机化)
engagement = 评论数 × 2.0 + 参与人数 × 3.0 + 浏览量 × 0.05
hours = max(1, 距发布小时数)
score = engagement / (hours + 2)^gravity
- 从候选时间窗口内(默认近 60 天)取 80 条候选
- 按热度分降序排列
- 取前 N×3 条组成随机池
- shuffle 后选取前 N 条
热门浏览随机化
- 按浏览量降序取前 N×3 条(可设最低门槛过滤)
- shuffle 后取前 N 条
缓存与预热
三栏各一个缓存键:lcoy-recommendations:v2:{recommended,latest,most_viewed}。
每栏的 TTL 依次取:栏目设置 → 基础 cache_ttl → 0(关闭)。
| 事件 | 失效范围 |
|---|---|
| 新帖发布 | 仅「最新」栏目 |
| 标题变更 | 全部三个栏目 |
| 帖子被隐藏 / 删除 / 恢复 | 全部三个栏目 |
保存任一 lcoy-recommendations.* 设置 | 全部三个栏目 |
失效是立即的,随后由预热任务在后台补齐。预热只重建缺失的栏目, 栏目 TTL 始终是新鲜度的权威,不会被预热周期悄悄重置:
php flarum recommendations:warm # 入队预热(只补缺失的栏目)
php flarum recommendations:warm --sync # 在当前进程强制重建
php flarum schedule:run # 15 分钟定时预热所依赖的调度入口
预热是可选的。没有队列 worker 时,任务会在触发它的写请求里内联执行;如果完全没有预热, 缓存过期后的第一个读请求会同步重建(约 15 ms),小部件照常渲染。关闭缓存或缓存后端不可用时, 每个请求都退回直接构建——不会报错,也不会白屏。
技术架构
lcoy/recommendations
├── src/
│ ├── Api/Controller/
│ │ └── ListRecommendationsController.php # API 控制器(仅协议层)
│ ├── Console/
│ │ └── WarmRecommendationsCommand.php # recommendations:warm 预热命令
│ ├── Job/
│ │ └── WarmRecommendations.php # 队列预热任务
│ └── Service/
│ ├── HotnessCalculator.php # 热度算法
│ └── RecommendationsBuilder.php # 缓存键/TTL/构建/序列化的唯一实现
├── 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 # 热度算法性质测试
│ └── RecommendationsBuilderTest.php # 缓存 TTL 解析测试
├── extend.php # 扩展入口
├── phpunit.xml.dist # 测试配置
└── composer.json
开发
composer test # 运行单元测试
composer analyse:php # 静态分析(需先安装 require-dev 依赖)
可见性说明
三个栏目对所有用户共用同一份缓存,因此内容一律按访客视角构建(whereVisibleTo(Guest)),
自动复用 Flarum 及各扩展注册的可见性作用域:
- 私密帖子、已隐藏帖子、零回复帖子(核心作用域)
- 受限标签内的帖子、未审核通过的帖子(
flarum/tags、flarum/approval等扩展作用域)
这保证了受限内容不会因缓存共享而泄露给访客。副作用是:登录用户也不会在小部件中看到 上述受限内容——这是共享缓存的必要取舍。
许可证
MIT