README

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.
📜 Official rules — publish the full terms (eligibility, how winners are selected, deadlines, odds, sponsor) in their own section on the giveaway page, separate from the short description, for communities whose local law requires them.
➗ Skill-testing question — optionally require the drawn winner to answer a question correctly before the prize is awarded, for jurisdictions (Canada among them) where a pure game of chance would be an illegal lottery. Entering stays one click; the question is put to the winner at claim time. Optionally set how many wrong answers are allowed before the winner forfeits and the prize is redrawn — the replacement is the next entrant the same published seed picks, so the result stays verifiable. Answer checking ignores case, spaces and thousands separators, and compares numeric answers as numbers.
⏱️ 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.
📦 Prize claiming — winners get a "You won!" banner with a one-click Claim button; the host is notified and can see per-winner claim status, plus optional claim instructions (e.g. "DM me your address").
🛡️ 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.
🧩 Giveaway cards in posts — paste a giveaway's link on a line of its own and the post shows the giveaway's card. Every link on a page is looked up in one request, and a link to a giveaway that no longer exists stays a plain link. Works with flarum/markdown and with Scribe.
🖼️ Cover from your media library — with fof/upload enabled, the cover image field gets a Media library button: pick an image you uploaded before, or upload a new one, in fof/upload's own media manager.
✍️ Add a giveaway from the composer — an Add giveaway button in the discussion and reply composers. The giveaway is saved as a draft only you can see, its link goes into your post, and it goes public when the post is posted (or approved, with flarum/approval). Saving the post as a fof/drafts draft — or scheduling it — keeps the giveaway a draft until the post goes up.
📝 Drafts — save any giveaway as a draft and publish it when ready. The list page has All / Open / Ended / Drafts tabs; Drafts only shows for members who have some.
🗓️ Start and draw times — the giveaway page shows when it starts (if set) and when it is drawn; before the start it reads "Starts in…" and entry opens on time.
🎫 One prize per winner — list one prize per line (gift codes, keys…): winner #1 gets line 1, winner #2 line 2, and so on. Each winner sees only their own line, and only after claiming. The winner count shows next to the prize (× 10).
👥 Participants list — the host, managers and anyone with View giveaway participants can see who entered and when, a page at a time.
🖋️ Formatted descriptions and rules — written in the forum's own editor and rendered by Flarum's formatter, exactly like a post: links, lists, bold and italic, safely.
🔐 Granular permissions — separate enter, create own, view participants 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

composer update ernestdefoe/giveaways
php flarum migrate
php flarum cache:clear

How the fair draw works

When a giveaway is drawn:

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.
A random seed is generated.
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.viewParticipants`	Moderators	See who entered a giveaway, and when (a host always sees their own)
`giveaways.manage`	Admins	Manage all giveaways

ernestdefoe / giveaways

Package info

Security

Fund package maintenance!

Statistics