Giveaways

Run provably-fair giveaways on your Flarum community. Members enter with one click, earn bonus entries for being active, and winners are drawn automatically — with a published seed and entrant fingerprint anyone can verify.

Features

• 🎁 Beautiful giveaways page — a dedicated /giveaways page with cards, live countdowns, status badges and entrant counts.

• 🎟️ One-click entry — registered members enter instantly. The button shows their current entry count.

• ⭐ Earn-entries engine — grant a one-time bonus when entrants post in the community, rewarding real activity.

• 🗂️ Categories — organise giveaways into colour-coded categories with filter pills, badges and an inline manager.

• 🎯 Eligibility rules — optionally require a minimum post count or account age to enter.

• ⏱️ Scheduled auto-draw — set an end time and the winners are drawn automatically by the scheduler. Hosts can also draw now at any time.

• 🔔 Winner notifications — every winner gets an in-app alert linking straight to the giveaway.

• 🛡️ Provably fair — every draw publishes a random seed and a SHA-256 hash of the full entrant list, so the result is independently reproducible and tamper-evident.

• 🏆 Multiple winners — draw any number of weighted winners in a single fair pass.

• 🔐 Granular permissions — separate enter, create own, and manage all permissions.

Screenshots

Giveaway page — enter, requirements & live countdown

Provably-fair results — published winners, seed & entrant hash

Installation

composer require ernestdefoe/giveaways

Then enable Giveaways in your admin panel and review the permissions grid.

Scheduled draws require Flarum's scheduler to be running. Add this to your server's crontab:

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

Without it, giveaways won't auto-draw at their end time — but you can still draw manually from each giveaway page.

Updating

php flarum migrate
php flarum cache:clear```

## How the fair draw works

When a giveaway is drawn:

1. The full entrant list is serialized in a fixed order (`userId:entries`, sorted by user id) and hashed with **SHA-256** — this is the **entrant hash**.
2. A random **seed** is generated.
3. For each winner slot *i*, the winner is chosen by `SHA-256(seed:i)` reduced over the weighted entry pool, removing each winner before the next pick.

Because the seed and entrant hash are published on the giveaway page, anyone can re-run the algorithm and confirm the winners were not manipulated.

## Permissions

| Permission | Default | Description |

|---|---|---|

| `giveaways.enter` | Members | Enter giveaways |

| `giveaways.create` | Admins | Create and manage **own** giveaways |

| `giveaways.manage` | Admins | Manage **all** giveaways |

## Settings

* **Show a "Giveaways" link in the main navigation** — toggle the nav item.
* **Navigation label** — customise the link text.

## License

[MIT](https://github.com/ernestdefoe/giveaways/blob/main/LICENSE) © ernestdefoe

giveaways v0.1.0

First release of Giveaways — provably-fair giveaways & raffles for Flarum 2.

✨ Features

• 🎁 Dedicated /giveaways page with cards, live countdowns, status badges and entrant counts
• 🎟️ One-click entry for registered members
• ⭐ Earn-entries engine — one-time bonus when entrants post in the community
• 🗂️ Colour-coded categories with filter pills, badges and an inline manager
• 🎯 Eligibility rules — minimum post count / account age
• ⏱️ Scheduled auto-draw (plus manual draw now)
• 🔔 In-app winner notifications
• 🛡️ Provably fair — every draw publishes a random seed and a SHA-256 hash of the full entrant list, so results are independently reproducible and tamper-evident
• 🏆 Weighted multiple-winner draws
• 🔐 Granular permissions (enter / create own / manage all)

📦 Install

shcomposer require ernestdefoe/giveaways Enable Giveaways in admin, review the permissions grid, and make sure Flarum's scheduler is running for automatic draws.

View release on GitHub

giveaways v0.1.1

What's Changed

• 🗂️ Categories — colour-coded categories with filter pills on the index, badges on cards and the detail page, and an inline category manager.
• 🔔 Winner notifications — every winner now gets an in-app alert linking straight to the giveaway.
• 🐛 Fixed: the "Giveaways" nav link now appears in the sidebar (registered on IndexSidebar).
• 🐛 Fixed: creating/editing a giveaway — the Save button now works (modal switched to Flarum 2's FormModal).
• 📸 README screenshots.

Full Changelog: https://github.com/ernestdefoe/giveaways/compare/v0.1.0...v0.1.1

View release on GitHub

giveaways v0.1.2

What's Changed

• 🌐 Fully translatable — all remaining server-side messages (entry eligibility + create/edit validation) now route through the translator, so the entire extension can be localized. New ernestdefoe-giveaways.api.* locale keys.

Full Changelog: https://github.com/ernestdefoe/giveaways/compare/v0.1.1...v0.1.2

View release on GitHub

giveaways v0.2.0

What's Changed

• 📦 Prize claiming — winners now see a You won! banner with a one-click Claim button. Hosts get notified when a prize is claimed, can see per-winner claim status, and can set optional claim instructions (e.g. "DM me your shipping address") shown to winners after they claim.
• Fully translatable; no migration required.

Full Changelog: https://github.com/ernestdefoe/giveaways/compare/v0.1.2...v0.2.0

View release on GitHub

giveaways v0.2.1

Floxum audit hardening (→ ≥95). Killed the presenter N+1, scoped AwardPostBonus + added an error boundary, FIELD() → portable CASE ordering (PG/SQLite-safe), serializer → presenter, canManage → Giveaway::canBeManagedBy(), cover_url CSS sanitisation, cascade FKs on entries/winners, and removed the dead discussion_id. Also fixes the manage-categories dialog icon being invisible for light colours (support d/55).

View release on GitHub