PHPackages                             wszdb/flarum-homefilter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Search & Filtering](/categories/search)
4. /
5. wszdb/flarum-homefilter

ActiveFlarum-extension[Search & Filtering](/categories/search)

wszdb/flarum-homefilter
=======================

Intelligent home page post filtering with keyword-based quantity control

v0.8(6mo ago)292MITPHPCI failing

Since Oct 21Pushed 6mo agoCompare

[ Source](https://github.com/wszdb/flarum-homefilter)[ Packagist](https://packagist.org/packages/wszdb/flarum-homefilter)[ RSS](/packages/wszdb-flarum-homefilter/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (8)Dependencies (1)Versions (9)Used By (0)

Flarum Home Filter
==================

[](#flarum-home-filter)

English | [简体中文](README.zh-CN.md)

An intelligent Flarum extension for filtering homepage discussions by **title** or **tags**, with flexible control over the display quantity of specific types of posts.

✨ Features
----------

[](#-features)

### 🎯 Dual Filtering Modes

[](#-dual-filtering-modes)

- **Title Filter Mode**: Filter discussions based on keywords in titles
- **Tags Filter Mode**: Filter discussions based on keywords in tags

### 🔧 Flexible Configuration

[](#-flexible-configuration)

- Customize filter keywords (supports multiple keywords, comma-separated)
- Set display limit for keyword-matched discussions
- Easy mode switching in admin panel
- **NEW**: Multiple supplement strategies (default/unread random)
- **NEW**: Flexible sort modes (time descending/random)

### 🚀 Smart Supplementing

[](#-smart-supplementing)

- Automatically supplement non-keyword discussions to maintain homepage count
- Prevents homepage from having insufficient discussions after filtering
- **NEW**: Respects hidden tags from flarum/tags extension
- **NEW**: Smart unread-based random supplement with configurable count

### 🎲 Advanced Features

[](#-advanced-features)

- **Hidden Tags Support**: Automatically filters out discussions with hidden tags
- **Unread Random Mode**: Randomly select from user's recent X unread posts
- **Random Sort**: Randomize homepage discussion order while keeping sticky posts on top
- **Sticky Posts Priority**: Sticky posts always appear first regardless of sort mode
- **Graceful Fallback**: Automatically falls back to default mode when all posts are read

📦 Installation
--------------

[](#-installation)

Install via Composer:

```
composer require wszdb/flarum-homefilter
```

Enable the extension in Flarum admin panel after installation.

⚙️ Configuration
----------------

[](#️-configuration)

Navigate to Flarum Admin → Extensions → Home Filter to configure:

### 1. Filter Keywords

[](#1-filter-keywords)

Enter keywords to filter, separated by commas.

**Example:**

```
ad,spam,promotion

```

### 2. Filter Mode

[](#2-filter-mode)

Choose filtering method:

- **Title Filter**: Check if discussion title contains keywords
- **Tags Filter**: Check if discussion tags contain keywords (requires flarum/tags extension)

### 3. Keyword Posts Display Limit

[](#3-keyword-posts-display-limit)

Set the maximum number of keyword-matched posts to display on homepage.

- Set to `3`: Display maximum 3 keyword-matched posts
- Set to `0`: Completely hide keyword-matched posts

### 4. Supplement Strategy (NEW)

[](#4-supplement-strategy-new)

Choose how to supplement discussions when homepage needs more posts:

- **Default**: Supplement with latest posts in time descending order (original behavior)
- **Unread Random**: Randomly select from user's recent unread posts
    - For logged-in users: Only unread posts are selected
    - For guests: All posts are considered unread
    - Automatically falls back to default mode if no unread posts available

### 5. Unread Posts Count (NEW)

[](#5-unread-posts-count-new)

Set how many recent unread posts to consider for "Unread Random" mode.

- Default: `50` posts
- Minimum: `20` posts
- Maximum: Unlimited (but recommend keeping under 100 for performance)
- Only the most recent X unread posts will be randomly selected from

### 6. Homepage Sort Mode (NEW)

[](#6-homepage-sort-mode-new)

Choose how to sort homepage discussions:

- **Time Descending**: Latest replied posts appear first (default)
- **Random**: Randomize post order on each page load
- **Note**: Sticky posts always appear first regardless of sort mode

💡 Use Cases
-----------

[](#-use-cases)

### Case 1: Limit Advertisement Posts

[](#case-1-limit-advertisement-posts)

```
Keywords: ad,promotion,marketing
Filter Mode: Title Filter
Display Limit: 2
Supplement Strategy: Default
Sort Mode: Time Descending

```

Effect: Homepage shows maximum 2 posts with "ad", "promotion" or "marketing" in title.

### Case 2: Control Specific Categories

[](#case-2-control-specific-categories)

```
Keywords: General,Chat
Filter Mode: Tags Filter
Display Limit: 5
Supplement Strategy: Default
Sort Mode: Time Descending

```

Effect: Homepage shows maximum 5 posts tagged with "General" or "Chat".

### Case 3: Completely Hide Certain Content

[](#case-3-completely-hide-certain-content)

```
Keywords: spam,junk
Filter Mode: Title Filter
Display Limit: 0
Supplement Strategy: Default
Sort Mode: Time Descending

```

Effect: Completely hide posts with "spam" or "junk" in title.

### Case 4: Fresh Content Discovery (NEW)

[](#case-4-fresh-content-discovery-new)

```
Keywords: (empty)
Filter Mode: Title Filter
Display Limit: 5
Supplement Strategy: Unread Random
Unread Posts Count: 50
Sort Mode: Random

```

Effect:

- Show random posts from user's recent 50 unread posts
- Different content on each page refresh
- Great for content discovery and engagement
- Falls back to latest posts if all posts are read

### Case 5: Balanced Mix (NEW)

[](#case-5-balanced-mix-new)

```
Keywords: announcement
Filter Mode: Title Filter
Display Limit: 2
Supplement Strategy: Unread Random
Unread Posts Count: 100
Sort Mode: Random

```

Effect:

- Maximum 2 announcement posts
- Fill remaining slots with random posts from recent 100 unread posts
- Random order for variety (sticky posts still on top)
- Supplements with read posts if unread posts are insufficient

🔍 How It Works
--------------

[](#-how-it-works)

1. **Filtering**: Check homepage discussions, match based on selected mode (title/tags) and keywords
2. **Limiting**: Keep specified number of keyword-matched posts, filter out excess
3. **Hidden Tags Check**: Automatically exclude discussions with hidden tags (if flarum/tags is installed)
4. **Supplementing**: Auto-query and add non-keyword posts based on selected strategy
    - Default mode: Latest posts in time order
    - Unread Random mode: Random posts from recent X unread posts
    - Fallback: If no unread posts, supplement with read posts or fall back to default mode
5. **Sorting**: Apply selected sort mode (time/random) while keeping sticky posts on top
6. **Precision Control**: Ensure final display count matches homepage configuration

📊 Performance
-------------

[](#-performance)

- **Title Filter Mode**: Performance identical to vanilla Flarum
- **Tags Filter Mode**: Adds 1-2 database queries, using optimized JOIN queries
- **Unread Random Mode**: Highly optimized with controlled query limits
    - Queries exactly X posts (configurable, default 50)
    - Random shuffle in PHP memory (very fast)
    - Much faster than previous time-based filtering
- **Suitable For**: Most forums (daily visits < 50,000)

### Performance Improvements

[](#performance-improvements)

The new "Unread Posts Count" approach is **significantly faster** than the old "Days Range" approach:

- Old: Database-level random sorting on potentially hundreds of posts (slow)
- New: Fetch limited posts + memory-level shuffle (fast)
- Performance gain: 50-80% faster on medium to large forums

🤝 Contributing
--------------

[](#-contributing)

Issues and Pull Requests are welcome!

📄 License
---------

[](#-license)

MIT License

🔗 Links
-------

[](#-links)

- [GitHub Repository](https://github.com/wszdb/flarum-homefilter)
- [Flarum Official](https://flarum.org)
- [Flarum Discuss](https://discuss.flarum.org)

💬 Support
---------

[](#-support)

For questions or suggestions, please submit an Issue on GitHub.

---

This extension was fully developed using [AiPy](https://www.aipyaipy.com/). Invitation code: XOFS.

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance69

Regular maintenance activity

Popularity15

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity30

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

8

Last Release

184d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/206fdad6f04e67cdf50359bafd70941f93ddf0488ae4c35513f08bdbf361a66c?d=identicon)[wszdb](/maintainers/wszdb)

---

Top Contributors

[![wszdb](https://avatars.githubusercontent.com/u/202256400?v=4)](https://github.com/wszdb "wszdb (3 commits)")

---

Tags

filterextensionflarumhome

### Embed Badge

![Health badge](/badges/wszdb-flarum-homefilter/health.svg)

```
[![Health](https://phpackages.com/badges/wszdb-flarum-homefilter/health.svg)](https://phpackages.com/packages/wszdb-flarum-homefilter)
```

###  Alternatives

[blomstra/search

Replaces Flarum search with one powered by an elastic search server.

114.9k](/packages/blomstra-search)[thrieu/yii2-grid-view-state

Save filters from GridView to session, keep the filter state between pages.

1313.1k1](/packages/thrieu-yii2-grid-view-state)[flarum-lang/french

French language pack to localize the Flarum forum software plus its official and third-party extensions.

2033.8k](/packages/flarum-lang-french)[flarum/gdpr

Features for GDPR, PII management

1425.2k15](/packages/flarum-gdpr)[clarkwinkelmann/flarum-ext-scout

Algolia and Meilisearch search for Flarum

124.2k1](/packages/clarkwinkelmann-flarum-ext-scout)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)