Search by

lcoy / recommendations

lcoy

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

Homepage

Issues

Forum

Type:flarum-extension

pkg:composer/lcoy/recommendations

Statistics

Installs: 9

Dependents: 0

Suggesters: 0

v1.9.0 2026-11-21 08:09 UTC

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

PackageTypeNotes
flarum/coreRequired^2.0 — verified on Flarum 2.0.1 (2.0 stable)
fof/forum-widgets-coreRequired^2.0
fof/discussion-viewsRecommendedProvides view_count data. Without it, Most Viewed column has no data to rank
Redis cacheRecommendedBetter caching performance. Falls back to file cache
Queue worker / cronOptionalOnly 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:clear after a core upgrade. Flarum caches a compiled formatter that is bound to the core version; a stale entry can cause 500 errors on every page until it is rebuilt.

Admin Settings

10 configurable parameters under Admin → Forum Widgets → Recommendations:

SettingDefaultDescription
Recommended Count5Items shown in Recommended column
Gravity Factor1.5Time-decay strength (higher = newer posts favored)
Candidate Window (days)60Only discussions created within this window can be recommended
Latest Count5Items shown in Latest column
Most Viewed Count5Items shown in Most Viewed column
Min View Threshold0Minimum views to enter candidate pool (0 = no limit)
Cache TTL (minutes)15Base cache duration (0 = disabled)
Recommended TTL (minutes)0Per-column override; 0 follows the base duration
Latest TTL (minutes)0Per-column override; 0 follows the base duration
Most Viewed TTL (minutes)0Per-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
  1. Fetch top 80 candidates within the candidate window (60 days by default)
  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

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).

EventInvalidated
New discussion postedLatest only
Title renamedAll columns
Discussion hidden / deleted / restoredAll columns
Any lcoy-recommendations.* setting savedAll 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
  1. 从候选时间窗口内(默认近 60 天)取 80 条候选
  2. 按热度分降序排列
  3. 取前 N×3 条组成随机池
  4. shuffle 后选取前 N 条

热门浏览随机化

  1. 按浏览量降序取前 N×3 条(可设最低门槛过滤)
  2. 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