Giveaways

ernestdefoe

🎁 Giveaways — run prizes your members can actually trust

Giveaways are one of the best ways to light up a quiet forum: people enter, people post, people come back to see if they won. But there's always that nagging doubt in the back of someone's mind — was it really random, or did the host just pick their friend?

Giveaways kills that doubt for good. Every prize draw is provably fair: the result is published with a seed and a fingerprint of the entrant list, so anyone can check the math themselves and confirm nobody put a thumb on the scale. Real excitement, zero suspicion.

One-click to enter. Bonus entries for being active. Winners drawn automatically — and verifiable by anyone.

🛡️ Provably fair, in plain English

When a giveaway is drawn, the extension publishes two things right on the giveaway page:

a random seed, and
a fingerprint (SHA-256 hash) of the complete entrant list.
Because both are public, anyone can re-run the draw and get the exact same winners. If a single entry had been added, removed, or reweighted, the fingerprint wouldn't match. It's tamper-evident by design — the kind of transparency that turns "I bet it was rigged" into "okay, that's actually fair."

✨ What it does

🎁 A beautiful giveaways page — a dedicated /giveaways hub with cards, live countdowns, status badges, and entry counts at a glance.
🎟️ One-click entry — members enter instantly, and the button shows their current number of entries.
⭐ Earn-entries engine — reward real activity by granting bonus entries when members post in the community. Lurkers enter; contributors get an edge.
🗂️ Categories — organise giveaways into colour-coded categories with filter pills and badges, all managed inline.
🎯 Eligibility rules — optionally require a minimum post count or account age, so giveaways reward genuine members and shut out throwaway accounts.
⏱️ Scheduled auto-draw — set an end time and winners are drawn automatically. Want to end it early? Hit Draw now any time.
🏆 Multiple winners — draw any number of winners in a single fair pass, with entries properly weighted.
🔔 Winner notifications — every winner gets an in-app alert linking straight to the giveaway. No one misses their moment.
🔐 Granular permissions — separate controls for who can enter, who can create their own, and who can manage all giveaways.
---

🚀 Installation

composer require ernestdefoe/giveaways

Then enable Giveaways in your admin panel and review the permissions grid to decide who can enter, create, and manage.

For automatic draws: scheduled draws rely on Flarum's scheduler, so add this single line to your server's crontab (most hosts make this quick):

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

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

Updating

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

📄 License

Released under the MIT License © ernestdefoe — free to use, free to build on.

🔗 Links

📦 Packagist: https://packagist.org/packages/ernestdefoe/giveaways
🐙 GitHub: ernestdefoe/giveaways
💬 Support & questions: https://ernestdefoe.online
Got a feature idea or want to show off a giveaway you've run? Come share it on the support forum. Enjoy — and may the odds be ever in your members' favour! 🎉

自在の偶

bug found. category icon's font awesome is right, but icon won't show on manage categories dialog. on the giveaways listing page's category section, it shows normally.

ernestdefoe

自在の偶 That's not exactly a bug but more of an oversight. Will have that added by the end of the week.

pofonya

Uncaught Error: Pushing object of type giveaways not allowed, as type not yet registered in the store. at Store.ts:59:15

YGPY

Winner notifications are missing from the notification center (no link to the giveaway)

Bug

Per the feature spec (README: "Winner notifications — every winner gets an in-app alert linking straight to the giveaway"), each winner should receive an in-app notification containing a direct link to the giveaway.

Actual behavior: the giveawayWon / giveawayClaimed notifications never render in the notifications dropdown. The dropdown opens with HeaderList-content empty (the unread count badge still increments), so there is no row and therefore no clickable link to the giveaway. The browser console also logs:

Pushing object of type giveaways not allowed, as type not yet registered in the store.

Reproduced on two independent environments (local phpstudy + a VPS), so it is not a cache/environment issue.

Root cause

The backend correctly registers a JSON:API resource for giveaways (src/Api/Resource/GiveawayResource.php, type() === 'giveaways') and the notification API correctly returns the giveaway as the notification subject (verified in the live /api/notifications response, including the included giveaways resource and the data.content containing slug).

The frontend, however, never registers a Model for the giveaways JSON:API type. app.store.models only contains the core types, so:

Store.pushObject() (flarum/core/js/src/common/Store.ts, _lines 132-139) sees this.models['giveaways'] is not registered, drops the included subject from the store and throws the async error above.
notification.subject() therefore returns undefined.
The core notifications list (flarum/core/.../forum/components/NotificationList.js, page.items.forEach(...) → if (typeof subject === 'undefined') return;) silently skips the notification row, so the "you won" alert (and its href() link in js/src/forum/components/GiveawayWonNotification.tsx) is never rendered.

Steps to reproduce

Install & enable the extension (composer require ernestdefoe/giveaways).
Create a giveaway, enter it, and let it be drawn (or draw manually).
Wait for the giveawayWon notification to be created (also stored in notifications.data with slug — confirmed).
Open the notification center (bell icon) as the winner.
→ The list is empty / the notification row is missing; the giveaway alert never shows, so there is no direct link.

Fix

Register a frontend Model for the giveaways type so the notification subject deserializes. Local reproduction confirms this resolves it (the row renders and the existing href() correctly builds /giveaways/{slug}).

New file js/src/common/models/Giveaway.ts:

import Model from "flarum/common/Model";

export default class Giveaway extends Model {
  slug() {
    return Model.attribute<string>("slug").call(this);
  }
  title() {
    return Model.attribute<string>("title").call(this);
  }
  prize() {
    return Model.attribute<string>("prize").call(this);
  }
  status() {
    return Model.attribute<string>("status").call(this);
  }
  endsAt() {
    return Model.attribute<Date | null, string | null>("endsAt", Model.transformDate).call(this);
  }
  drawnAt() {
    return Model.attribute<Date | null, string | null>("drawnAt", Model.transformDate).call(this);
  }
}

Edit js/src/forum/index.ts — add the import and register the model in the initializer:

import Giveaway from "../common/models/Giveaway";

app.initializers.add("ernestdefoe-giveaways", () => {
  app.store.models.giveaways = Giveaway;
  // ... existing route / notification-component / nav registrations
});

Then rebuild: cd js && npm run build.
Environment

Flarum core: ².0
Extension: ernestdefoe/giveaways (v1.0.0 / MVP)
Reproduction URL/DB both verified locally and on a VPS

ernestdefoe

Giveaways v0.2.2

Fixed

Giveaway notifications never appeared. Winners were notified correctly on
the server, but the notification never showed up — the unread badge counted
up while the notifications dropdown stayed empty. Some forums also saw a
console error:

Uncaught Error: Pushing object of type giveaways not allowed, as type not yet registered in the store.

Both symptoms were the same bug. The backend was always correct — the
giveaway is sent as the notification's subject. But the frontend never
registered a model for the giveaways type, so the store discarded that
subject, the notification's subject came back undefined, and Flarum core
skips any notification whose subject is missing. Silently, which is why it
looked like no notification was ever sent.

Giveaway notifications now render and link through to the giveaway.

Extenders were being compiled but never applied. The extension's forum
entry point used a side-effect-only import, so the bundle's named exports
were dropped and Flarum never saw the extender array — the model
registration was in the built file and ignored at runtime.

Not affected

Browsing, entering and drawing giveaways. Those pages don't go through the
store, so they were never touched by this.
No settings, permissions or database changes. Upgrade is a drop-in
composer update ernestdefoe/giveaways plus a cache clear.

Thanks

pofonya for reporting the console error.
YGPY for the root-cause analysis and patch, reproduced on two
independent environments — the diagnosis was correct and is what shipped.

Mikasa1

Updated to version 0.2.3 - Single Giveaway page view return's white page with 2 error's in console:
TypeError: In fragments, vnodes must either all have keys or none have keys.

NotFoundError: Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node.

ernestdefoe

Mikasa1 I'll work on getting an update out ASAP.

ernestdefoe

Mikasa1

v0.2.4

Fixed

Every single-giveaway page was blank. Opening any giveaway on 0.2.3 gave a white page and two console errors:

TypeError: In fragments, vnodes must either all have keys or none have keys.
NotFoundError: Failed to execute 'removeChild' on 'Node'

The loading skeleton added in 0.2.3 built one children array holding three unkeyed vnodes and two keyed ones. Mithril's rule is per children array, not per element — every vnode in one array either has a key or none of them do — so m.render threw before drawing anything. That skeleton is the first thing a single-giveaway page renders, so the page never appeared at all.

The second error is the half-updated DOM that follows, not a separate fault. Fixing the first removes both.

The giveaway list page was never affected, which is why this got past me.

Reported by @Mikasa1 — thank you, and sorry it took a version to catch.

Also

npm test now renders both skeletons through real Mithril and fails the build if either one throws. It renders the actual source file rather than a copy of its markup, and it was confirmed to fail against the 0.2.3 file before being kept — a test that has never failed on the bug it was written for proves nothing.

Upgrade:

composer update ernestdefoe/giveaways

Then clear the asset cache.

jstebenne

I don't have time to test it, but is there a section for giveaway rules? Local laws require us to define clear rules and that can sometimes get pretty long (things like how are winners selected, answering a simple math question so it is not purely a game of luck/gambling, etc.)

ernestdefoe

jstebenne
Good catch — there wasn't one, and there is now in v0.3.0.

Official rules are their own field and their own section on the giveaway
page, separate from the short description. Long text is fine — up to 20,000
characters, with your line breaks preserved — so a full set of terms
(eligibility, how and when winners are selected, the deadline, odds, sponsor)
has somewhere to live that isn't the pitch above the Enter button.

Skill-testing questions are supported too, since "not purely a game of
chance" is a hard requirement in Canada and elsewhere. Set a question and its
answer on the giveaway; entrants see the question in the rules and again above
the Enter button, and the entry is only created if the answer is correct — it's
enforced on the server, not just prompted in the browser. Answer matching is
lenient about case, spaces and thousands separators, and compares numbers as
numbers, so 26, 26.0 and 26 all pass.

Both are optional; existing giveaways keep their one-click entry. Upgrading
runs one migration.

jstebenne

ernestdefoe NIce, but that implementation of the skill testing is incorrect in most jurisdictions, at least with my local laws. In the eyes of the law, having the skill to gain an entry does not make it different from gambling, since it becomes a prerequisite to the drawing. You still leave the winner defined by chance.

The drawing has to be only for the winner, and they only get one chance to get it right, otherwise they forfeit the prize. This is all working on a technicality where the winner of the drawing wins the right to do the skill challenge, thus getting the final prize.

Also, I don't know how to say this correctly (and I don't know how the rest if the rest of the community feels that way), but if I wanted a reply by Claude, I would have used my own Claude account. It would be nice to at least have a human replying and share real knowledge we can all learn from.

ernestdefoe

jstebenne will correct this but it will be Sunday before I can get a new version out and on the Claude stuff I just use it to give me the changelog of what was changed.

ernestdefoe

jstebenne Was actually quicker to fix that than I thought. 0.4.0 should have the fix you need in it. Actually hold off on 0.4.0 and wait for 0.5.0 which has the forfeit and redrawn that is required. 0.5.0 is out now which has the feature.

jstebenne

ernestdefoe No worries for the delay, I do not need the extension immediately anyway (giveaway is early in the planning stage), and my feature request would make it a lot easier to manage the legality of giveaways here (I could do a forum post, but having everything self-contained is much easier). Just a few years ago, all giveaways needed to be registered with the lottery office to pay a tax, and the law changed to not have that requirement anymore. However, everything must still fit inside a strict set of rules.

I love the features the extension provides, especially being provably fair. Using Claude for code and changelog makes a lot of sense and I trust that you do your best to review everything it does. You could look at tools like Git Cliff or GitHub Changelog Generator which can be integrated with GitHub Actions to build changelogs on release and remove the need to think about it. It would also automatically link changes in a release to the related work items, and since it's a script, it would save you a few tokens.

ernestdefoe

jstebenne well disclaimer I use Claude to build my extensions and drafts automatically get built when a new version gets built it adds a Changelog automatically and I tell Claude to tell me what changed and then I post it here.

ernestdefoe

Giveaways v0.5.2 — fair draws, whoever is hosting

Security update — please update. A member who could create giveaways could steer the result of their own: draw early against a small pool, cut the end short once people had entered, enter their own giveaway, change the skill-question answer after the draw so the winner's correct answer failed and the prize moved on, or delete a drawn giveaway and with it the record of who won. A winner could also get more guesses at the skill question than the limit allowed by sending answers all at once.

Fixed

A giveaway is drawn exactly once. When the scheduled draw and Draw now (or a double click) landed together, a giveaway could get two sets of winners and two rounds of "you won" alerts.
A wrong skill-question answer shows how many attempts are left. With an attempt limit set, every wrong answer used to show an error instead.
Extra guesses are no longer possible. Answers sent at once are judged one at a time, so the attempt limit holds and only one replacement winner is drawn.
"Log in to enter" opens the log-in window again for guests.
The giveaway pages and forms load only when opened: forum.js 32.4 → 7.5 KB (7.0 → 2.5 KB compressed).

Changed

These apply to hosts (members with "create giveaways"); managers keep every power they had.

A host can draw once the giveaway has ended, not before. The Draw button only shows when it will work. An early draw is a manager's call.
Once people have entered, a host can move the end later but not earlier.
Hosts cannot enter their own giveaway. They see "You're hosting this giveaway" instead of the Enter button.
Only managers can delete a giveaway that has been drawn. A host can still delete one that is running.
After the draw, the skill question, its answer, the attempt limit, the number of winners and the end time are fixed for everyone, managers included. Other fields still save.

composer require ernestdefoe/giveaways:^0.5.2
php flarum cache:clear

Release on GitHub