README

A powerful, AST-based moderation and filtering engine for Flarum.

Filter Rule Manager goes beyond simple word replacements. It allows forum administrators to build complex, logical rulesets that can dynamically evaluate post content, automatically flag suspicious behavior, require manual approval, or block posts entirely.

Features

Filter Rule Manager is built to give Flarum administrators fine-grained control over their community's content. It covers the following features out-of-the-box:

• Visual Rule Builder: Construct complex logic using an intuitive drag-and-drop interface. Group conditions using AND / OR / NOT logic to create highly specific content filters.
• Priority-based Execution: Order your rulesets. Higher priority rules execute first, efficiently preventing unnecessary processing on lower rulesets.
• Intervention Types: Choose exactly how the system reacts to a violation:
  • Info: Displays a real-time hint while the user is typing, but does not block them from submitting the post.
  • Warning: Displays a real-time hint and explicitly requires user confirmation (via a modal) before they can submit the post.
  • Block: Evaluated server-side upon submission. Prevents the post from being submitted entirely and displays an error message.
  • Silent: Does not display anything to the user. Evaluated silently on the server-side. (Note: You can configure any of the above to also automatically Flag the post or hold it for Approval.)
• Dynamic Scopes: Apply filtering rules globally, or restrict them to specific Tags or specific Discussions.
• Evasion Detection: Define strict timeout windows and strike thresholds. If a user repeatedly hits block rules (e.g., 3 times within 15 minutes), the system automatically escalates penalties, flagging their next clean post for moderator review.
• Bypass Groups: Exempt specific User Groups (e.g., Moderators, Admins) from individual rulesets.
• Customizable Messaging: Define dynamic flag reasons and block messages using variable interpolation (e.g., Matched word: {{matched_word}} or Triggered ruleset: {{ruleset}}). Messages support HTML.
• Extensible API: Other extensions can securely inject their own custom Rule Providers into the AST engine.

⚠️ Security & Privacy Note

Frontend Evaluation Disclosure: Filter Rule Manager evaluates Info and Warning rulesets instantly on the client-side to provide real-time feedback to users as they type. To achieve this, the system injects the full logic (including compiled word lists, regex patterns, and match conditions) of all active Info and Warning rulesets into the page payload for authenticated users.

A determined user could potentially inspect the page source to discover the exact patterns configured in these rulesets and attempt to bypass them.

Best Practice: Use Info and Warning interventions only for guidelines, formatting hints, or soft moderation. For strict filters (e.g., severe profanity, spam links, zero-tolerance policies) that you wish to keep hidden, use the Block or Silent intervention types. Block and Silent rulesets are evaluated strictly server-side and are never exposed to the browser.

Installation

Install with composer:

composer require huoxin/filter-rule-manager:"*"

Updating

composer update huoxin/filter-rule-manager:"*"
php flarum migrate
php flarum cache:clear

For Developers

Filter Rule Manager is built to be extended! If you are an extension developer and want to register custom Rule Providers (e.g., AI toxicity checks, image scanning, custom regex engines), please read the Extending Guide.

Screenshots

Links

• Packagist
• GitHub
• Discuss