Auto Moderator

Automatically assign groups based on activity.

Compatible with Flarum v1.8.3

Latest release v0.1.3


released on May 20, 2021

Auto Moderator

License Latest Stable Version

A Flarum extension.

Core Concept

The idea is simple: When X, if Y, do Z.

Let's define some key terms:

  • Triggers: A set of events (usually just one) that can trigger an automation. Triggers can provide For example, "Posted"
  • Metrics: A numerical condition. For example, post count or number of likes received. A criterion could require a range/minimum/maximum of metrics.
  • Requirement: An abstract boolean condition. For example, not being suspended, or having an email that matches a certain regex.
  • Action: Something that happens automatically when a criteria is met or lost. This could include anything from adding/removing a group to sending an email to suspending a user.

This makes for an extremely powerful extension. Furthermore, since extensions can add their own metrics, requirements, and actions, this extension can automate away a lot of moderation. Beyond the examples listed below, some things that could be possible are:

  • Automating assignment of achievements / badges
  • Sending emails/notifications to users when they reach thresholds (or just when they register)
  • Establishing a system of "trust levels" like Discourse
  • Onboard/offboard users to/from external systems when they receive/lose certain group membership
  • And a bunch more! The possibilities are endless.


When a trigger event occurs:

  • All metrics will be calculated for the relevant user (what is the numerical value of the metric?)
  • All requirements will be calculated for the relevant user (does the user satisfy each of the requirements?)
  • The user's new criteria group will be computed and diffed against the user's current criteria group. The two sets will be diffed. Only criteria triggered by the event will be adjusted.
  • Actions will be executed for any gained and lost criteria.

You can also use the php flarum criteria:recalculate console command to recalculate criteria for all users. Note that this will be quite slow, and shouldn't usually be done.


Example 1: Group Management

Criteria: Users that receive 50 or more likes and have started at least 10 discussions should placed in the "Active" group.

Here, the metrics are "received 50 or more likes" and "have started at least 10 discussions". Unsurprisingly, they come with the triggers (PostWasLiked, PostWasUnliked) and (Discussion\Started) respectively.

The actions are:

  • When the criteria is met, add the user to the "Active" group
  • When the criteria is lost, remove the user from the "Active" group

Example 2: Suspension

Criteria: If a user gets 15 warnings or more and is not an admin, suspend them.

Here, the metrics are "gets 15 warnings or more" and the requirements are "is not an admin". The triggers would be a new warning for the metric. The requirement has no triggers.

The actions are:

  • When the criteria is met, suspend them
  • When the criteria is lost, unsuspend them

Example 3: Auto Activation

Criteria: If a user's email matches a regex, activate their email.

The requirement is "a user's email matches a regex". The triggers are saving a user.

The actions are:

  • When the criteria is met, auto activate the user's email
  • When the criteria are not met, don't

Example 4: Default Group

Criteria: Add a user to a group

There are no metrics or requirements, so this will be applied to all users on login.

The actions are:

  • Add all users to a group on login


Admin Criterion Edit Edit User

Metrics vs Requirements

It's clear to see that any metric could be represented as a Requirement.

  • A requirement must be specific. "More than 50 received likes" could be a requirement. However, metrics can allow for any range of values.
  • Metrics can be stored and used for other purposes. For example, a planned feature is combining all metrics to provide a "reputation" score.


Requirements and actions can require settings in the admin dashboard. For example:

  • The "add to group" action takes the group ID as a setting
  • The "suspend" action takes the number of days and whether the suspension is indefinite as settings
  • The "email matches regex" requirement takes the regex as a setting


This extension is extremely flexible. It can be considered a framework for automoderation actions.

Extensions can use the Askvortsov\AutoModerator\Extend\AutoModerator extender to add:

  • Action drivers
  • Metric drivers
  • Requirement drivers

You should look at the source code of the default drivers for examples. They're fairly exhaustive of what's offered.

If your extension adds action or requirement drivers that consume settings, you have 2 options:

  • Provide translation keys for the settings you need in the driver's availableSettings method. This is very easy, but also very restrictive. You can only use strings, and can't add any restrictions or UI.
  • You can declare a settings form component for your driver. See js/src/admin/components/SuspendSelector for an example. The component should take a settings stream as this.attrs.settings. The contents of the stream should be an object that maps setting keys to values. The component is responsible for updating the stream on input. You can register a form component by adding its class to app.autoModeratorForms[DRIVER CATEGORY][TYPE], where DRIVER CATEGORY is "action" or "requirement", and TYPE is the type string you registered your driver with in extend.php. See js/src/admin/index.js for the underlying data structure and examples.


  • Add support for more metrics:
    • Posts read
    • Time spent on forum
    • Days visited
    • Days since account creation
    • Etc
  • Add support for dated metrics (discussions created in the past X days)
  • Introduce metric "weights", sum together to calculate a reputation. Make that reputation available as a metric.
  • Develop a data collection extension, which could cache things such as like counts, to improve performance on large forums
  • Investigate criterion "listeners": can we generalize stuff like removing links from posts of users without certain groups?


Contributions and PRs are welcome! Any PRs adding new drivers should come with unit tests (like with all existing drivers).


Compatible starting with Flarum 1.0.


composer require askvortsov/flarum-automod:*


composer update askvortsov/flarum-automod


When X, if Y, do Z

Triggers have:

  • Name
  • "Short Formatter"
  • List of subject classnames
  • subject getter
  • Event classname

Metrics/Requirements have:

  • Name
  • "Short Formatter"
  • Subject classname
  • Value "getter"
  • Settings setter / validator (requirements only)

Actions have:

  • Name
  • Subject
  • Settings setter / validator
  • Side effect "executor"

Rules store:

  • List of triggers
  • List of (negatable) metrics + requirements
  • List of actions

© 2023 Hyn by DaniĆ«l "Luceos" Klabbers. All rights reserved. · Extensions and extension information is provided by the respective (copyright holding) authors. · Extiverse is not affiliated to the Flarum project or Flarum foundation. · Images on Extiverse pages are from Unsplash.