README

Leaderboard

A points-based leaderboard extension for Flarum forums. Award points for community activity, display rankings with a beautiful podium, and motivate engagement through configurable point sources and time-based filters.

🏆 Podium & Rankings

📊 Top Contenders & Honorable Mentions

⚙️ Admin General Settings

⚙️ Admin Points Settings

⚙️ Admin Exclusions Settings

⚙️ Admin Maintenance Settings

⚙️ Admin Recalculate Modal

Features

• 🏆 Podium Display: Top 3 users shown in a gold/silver/bronze podium with avatars and stats
• 🔥 Top Contenders: Ranks #4-#10 displayed in a responsive card grid
• 📋 Honorable Mentions: Compact two-column list for remaining users with infinite scroll
• ⏰ Period Filters: Daily, weekly, monthly, quarterly, yearly, and all-time rankings
• ⭐ Configurable Points: Set point values for each activity type independently
• 🎯 11 Point Sources: Discussions, posts, daily login, likes (given/received), reactions (given/received), best answers, badges, and votes
• 🏷️ Tag Exclusions: Exclude discussions with specific tags from earning points
• 👥 Group Exclusions: Hide users in selected groups from the leaderboard
• 🔄 Maintenance Tools: Full recalculation and lightweight sync for point adjustments
• 🦴 Skeleton Loading: Smooth loading experience with animated placeholders
• 📱 Responsive Design: Optimized layout for mobile, tablet, and desktop
• 🃏 User Card Integration: Show leaderboard points on user cards throughout the forum

Installation

composer require huseyinfiliz/leaderboard:"*"

You can also install with Extension Manager: huseyinfiliz/leaderboard

Updating

composer update huseyinfiliz/leaderboard
php flarum migrate
php flarum cache:clear

To remove simply run composer remove huseyinfiliz/leaderboard.

Quick Start

For Users

1. Navigate to the Leaderboard page from the sidebar
2. Use period pills to filter rankings (Daily, Weekly, Monthly, etc.)
3. Click on any user card to visit their profile
4. Your points are visible on your user card across the forum

For Admins

Navigate to Admin → Leaderboard to configure the extension. The admin panel is organized into four tabs:

General Tab

• Leaderboard Name: Customize the page title displayed in the sidebar and header
• Points Label: Set the label shown next to point values (e.g., "Points", "XP", "Karma")

Points Tab

Configure point values for each activity type. Points are organized into collapsible sections:

Tip: Set a point value to 0 to disable that source. Negative values (e.g., downvotes) deduct points.

Exclusions Tab

• Excluded Groups: Select user groups to hide from the leaderboard (e.g., Admins, Bots)
• Excluded Tags: Select tags whose discussions won't earn points (requires flarum/tags)

Maintenance Tab

Note: Do not close the page during a full recalculation — the operation will fail if interrupted.

Optional Integrations

The leaderboard automatically integrates with these extensions when they are enabled:

No configuration is needed — install the extension and points will be awarded automatically based on your point settings.

🔧 Advanced Details

Point Lifecycle

Points are awarded and revoked automatically based on user activity:

Action performed → Points awarded → Totals updated
Action undone    → Points revoked → Totals updated

Data Integrity

• Atomic operations: Point revocations use database transactions with row locking
• Cascade handling: Discussion deletion properly revokes all post-level points (likes, reactions, votes)
• Content moderation: Hidden posts/discussions have their points revoked; restored content re-awards points
• Idempotent awards: Duplicate point records are prevented with existence checks
• Daily login protection: Database fallback prevents double-awarding after cache clear

Period Filtering

Rankings are filtered by the created_at timestamp of each point record:

🌍 Translations

This extension comes with English translations. Community translations are welcome!

Translate: Leaderboard at Weblate

💖 Support & Contributing

If you find this extension useful, consider:

• ⭐ Starring the repository on GitHub
• 🌐 Contributing translations

Links

• Discuss
• Packagist
• GitHub
• Issues

License

MIT License - see LICENSE.md

Developed with ❤️ by Hüseyin Filiz