README

A Flarum extension that automatically synchronizes your Open Collective backers with Flarum user groups.

Features

• 🔄 Automatic Synchronization: Hourly checks for new and removed backers
• 👥 Smart User Matching: Matches backers via email addresses
• 🎯 Dual Group Support: Separate groups for recurring and one-time backers
• 🔄 Status-Based Categorization: Automatically moves past recurring backers to one-time group
• 🔒 Safe Group Management: Only manages users it adds, won't interfere with manually assigned groups
• 📝 Detailed Logging: Tracks all changes in dedicated log files
• 🧪 Dry-Run Mode: Preview changes before applying them
• 📊 Verbose Output: Detailed information about the synchronization process

How It Works

This extension connects your Open Collective account with your Flarum forum by:

1. Fetching Backers: Queries Open Collective's GraphQL API to retrieve your current backers (active recurring, cancelled recurring, and one-time contributors)
2. Categorizing Backers: Separates backers into two groups:
   • Recurring backers: Users with active monthly or yearly subscriptions
   • One-time backers: Users who made one-time contributions or whose recurring subscription has ended
3. Matching Users: Identifies Flarum users by matching email addresses from Open Collective backers with Flarum user emails
4. Managing Groups: Automatically adds backers to designated Flarum groups and removes users who are no longer backers
5. Handling Transitions: When a recurring backer's subscription ends, they are automatically moved to the one-time backers group
6. Tracking Changes: Logs all additions, removals, and transitions to help you monitor the process

Installation

Install with composer:

composer require fof/open-collective:"*"
php flarum migrate
php flarum cache:clear

Required: Flarum Scheduler

This extension requires Flarum's scheduler to be set up and running. The extension will automatically check for backer updates every hour.

Add this cron job to your server:

* * * * * cd /path-to-your-project && php flarum schedule:run >> /dev/null 2>&1

Configuration

After installation, configure the extension in your Flarum admin panel:

1. Create an Open Collective Personal Token

1. Go to Open Collective Applications
2. Create a new Personal Token
3. Copy the token (you won't be able to see it again)

Legacy API Keys: If you have an existing legacy API key, you can continue using it by enabling "Use Legacy Application API Key" in the settings. However, it's recommended to migrate to a Personal Token.

2. Configure the Extension

In your Flarum admin panel, navigate to the Open Collective extension settings:

• Personal Token (or API Key if using legacy): Paste your Open Collective token
• Collective Slug: Enter your collective slug (e.g., if your collective is at opencollective.com/your-collective, enter your-collective)
• Recurring Backers Group: Select which Flarum group to assign to recurring backers (required)
• One-Time Backers Group: Optionally select a group for one-time backers and past recurring backers (optional)

Note: If you only configure the recurring backers group, all backers (both recurring and one-time) will be added to that single group. If you configure both groups, the extension will automatically categorize backers based on their subscription status.

Save the settings, and the extension will start syncing on the next scheduled run.

Usage

Once configured, the extension runs automatically every hour. You can also manually trigger an update:

php flarum fof:open-collective:update

Command Options

Dry-Run Mode

Preview what changes would be made without actually applying them:

php flarum fof:open-collective:update --dry-run

This is useful for testing your configuration before letting the extension make real changes to your groups.

Verbose Output

Get detailed information about the synchronization process:

php flarum fof:open-collective:update -v

Verbose mode shows:

• Configuration details (API type, collective slug, target groups)
• Total number of backers and breakdown by type (recurring vs one-time)
• All backers from Open Collective with their emails and type
• Matched Flarum users for each group
• Unmatched backers who couldn't be linked to Flarum accounts
• Summary of users staying, being added, removed, and moved between groups

Combine both options for detailed preview:

php flarum fof:open-collective:update --dry-run -v

Viewing Logs

Check the synchronization logs:

tail -f storage/logs/fof-open-collective.log

Log output includes:

• Number of backers found on Open Collective
• Number of backers matched to Flarum users
• Users added to the group (with + #userID username)
• Users removed from the group (with - #userID username)
• Any API errors or configuration issues

How User Matching Works

The extension matches Open Collective backers to Flarum users by comparing email addresses. For a backer to be matched:

• The backer must have a public email address on their Open Collective profile
• A Flarum user must exist with that same email address
• The Flarum user's email must be confirmed

Important Notes

• Safe Group Management: The extension only removes the group from users it previously added. It won't affect users who were manually added to the group.
• Email Matching: Users must have the same email address as their Open Collective account.
• Backer Categorization:
  • Users with active monthly or yearly subscriptions are placed in the recurring backers group
  • Users who made one-time contributions or whose subscription has ended are placed in the one-time backers group
  • When a recurring subscription ends, the user is automatically moved to the one-time group (if configured)
• Rate Limits: The Open Collective API has rate limits. The extension checks once per hour to stay well within these limits.
• Email Privacy: Some backers may have private email addresses on Open Collective. These backers cannot be matched to Flarum users automatically.

For Developers: Event System

This extension dispatches events when backers are added or removed, allowing other extensions to react to these changes.

Available Events

FoF\OpenCollective\Event\BackerAdded

Dispatched when a user is added to the backers group.

Properties:

• $user (Flarum\User\User) - The Flarum user who was added
• $backerData (object|null) - Open Collective backer data including:
  • email - Backer's email address
  • Other fields from the Open Collective API

Example listener:

use Flarum\Extend;
use FoF\OpenCollective\Event\BackerAdded;

return [
    (new Extend\Event)
        ->listen(BackerAdded::class, function (BackerAdded $event) {
            $user = $event->user;
            $email = $event->backerData->email ?? null;

            // Your custom logic here
            // e.g., send a welcome email, grant additional permissions, etc.
        }),
];

FoF\OpenCollective\Event\BackerRemoved

Dispatched when a user is removed from the backers group (backing ended).

Properties:

• $user (Flarum\User\User) - The Flarum user who was removed

Example listener:

use Flarum\Extend;
use FoF\OpenCollective\Event\BackerRemoved;

return [
    (new Extend\Event)
        ->listen(BackerRemoved::class, function (BackerRemoved $event) {
            $user = $event->user;

            // Your custom logic here
            // e.g., send a thank you message, revoke special access, etc.
        }),
];

Notes on Events

• Events are not dispatched when running with the --dry-run flag
• Events fire after the database changes have been made
• The BackerAdded event includes raw Open Collective data for additional context
• These events only fire for automated changes, not manual group assignments

Troubleshooting

No backers are being synced

• Verify your token is correct and has proper permissions
• Check that the collective slug matches your Open Collective account exactly
• Ensure the cron job is running (schedule:run)
• Check logs in storage/logs/fof-open-collective.log

Some backers aren't being matched

• Ensure backers have public email addresses on their Open Collective profiles
• Verify that corresponding Flarum users exist with the same email addresses
• Check that Flarum user emails are confirmed

Authentication errors

• If using a Personal Token, ensure it was created correctly
• If using a legacy API Key, consider migrating to a Personal Token
• Check that the token hasn't expired or been revoked

Updating

composer update fof/open-collective
php flarum migrate
php flarum cache:clear

Links

• Packagist
• GitHub
• Discuss

An extension by FriendsOfFlarum.