Calendar & Events for Flarum

A full-featured, free calendar & events extension for Flarum 2. Month and

list views, RSVPs, colour-coded categories, recurring events, cover images, a

proper iCal feed, one-click Google Calendar export, and a drop-anywhere

Upcoming Events widget that looks right on the default theme — and integrates

natively with Bespoke and

Page Builder.

Built to feel premium. Priced at free.

---

Features

• 🗓️ Month, Week, Day & list views with quick prev / today / next navigation.

  Week/Day are true time grids with hour lines, a live "now" indicator, side-by-side

  overlapping events, and double-click-to-create at the clicked time slot.

• 📍 Location on every event, rendered as a one-tap Google Maps link.

• 🔁 Recurring events (daily / weekly / monthly / yearly) via standard RRULE,

  expanded on the fly so each occurrence shows on the right day.

• ✅ RSVP — members mark themselves Going or Interested, with live counts.

• 🎨 Categories with colours — filter the calendar and give each event a

  coloured accent. Managed from a dedicated admin panel with a colour picker.

• 🖼️ Cover image per event — paste a URL, or upload a file directly when

  FoF Upload is installed (auto-detected;

  falls back to a URL field otherwise).

• 📅 iCal export — a subscribable feed.ics for the whole calendar plus a

  per-event .ics download (RFC 5545, proper escaping & folding).

• 🟦 Google Calendar — "Add to Google Calendar" deep-links with title, time,

  description and location pre-filled.

• 💬 Optional discussion thread per event (hybrid model) so members can

  comment using Flarum's native discussion UI.

• 🧩 Upcoming Events widget — works standalone on the default theme, and

  registers as a first-class widget/block in Bespoke and Page Builder.

• 🌓 Theme-aware — every colour resolves through Flarum's own CSS variables,

  so it looks correct in light & dark and on custom themes out of the box.

• 🔐 Permissions — separate "create events" and "manage all events" controls.

Installation

php flarum migrate
php flarum cache:clear```

Then open **Admin → Calendar** to configure it.

## Updating

```composer update ernestdefoe/calendar
php flarum migrate
php flarum cache:clear```

## Configuration

**Admin → Calendar** gives you:

| Setting | What it does |

| --- | --- |

| **Default view** | Month grid or upcoming list when the calendar opens. |

| **Week starts on** | Sunday or Monday. |

| **Index widget** | Show an "Upcoming events" widget on the forum index. |

| **Widget count** | How many upcoming events the widget lists. |

| **Link discussion** | Auto-create a discussion thread for each new event (for comments). |

| **Categories** | Add / rename / recolour / delete colour-coded categories. |

Two permissions are added under **Admin → Permissions**:

* **Create calendar events** — who can add events.
* **Manage all calendar events** — who can edit/delete events they don't own.

## The Upcoming Events widget

The widget is a self-contained component, so it shows up automatically wherever

your theme supports it:

* **Default theme** — appears in the index sidebar (toggle in admin).
* **Bespoke** — available in the widget tray as **Upcoming events**.
* **Page Builder** — available as an **Events** block.

## Calendar subscription (iCal)

Every calendar exposes a subscribable feed at:

```https://your-forum.example/calendar/feed.ics```

Paste that URL into Google Calendar (*Other calendars → From URL*), Apple

Calendar (*File → New Calendar Subscription*), or Outlook to keep events in sync.

Each event also has its own `.ics` download and an "Add to Google Calendar" link.

## How events are modelled

Events are their own records (title, time, location, recurrence, etc.). When

**Link discussion** is enabled, creating an event also spins up a normal Flarum

discussion linked to it, so comments, mentions, likes and notifications all work

exactly as members expect — no parallel comment system to learn.

## Compatibility

* Flarum `^2.0`
* PHP `^8.3`
* No required third-party extensions. Plays nicely with Bespoke & Page Builder

  when present, and degrades gracefully when they aren't.
* **Optional:** [FoF Upload](https://github.com/FriendsOfFlarum/upload) — enables

  drag-free file uploads for event cover images.

## Contributing

Issues and PRs welcome. To build the front-end locally:

```cd js
npm install
npm run dev      # watch
npm run build    # production```

## License

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

calendar 2.0.1

What's Changed

• Phase A: engagement engine — activity heatmap, streaks & forum pulse
• Phase B: live countdowns — [countdown=…] in posts + event countdowns
• Phase C + D: On This Day memories + member celebrations (birthdays/anniversaries)
• docs: README — document the engagement engine (heatmap, pulse, countdowns, memories, celebrations)
• Fix calendar admin: missing widget-toggle labels + CategoryManager spinner loop
• Fix CategoryManager render crash: key the 'add' row (mixed keyed/unkeyed fragment)

Full Changelog: https://github.com/ernestdefoe/calendar/compare/2.0.0...2.0.1

View release on GitHub

calendar 2.0.2

What's Changed

• Fix create-event (no form wrapper), redesign event modal, use default loader

Full Changelog: https://github.com/ernestdefoe/calendar/compare/2.0.1...2.0.2

View release on GitHub

calendar 2.0.3

What's Changed

• Page Builder: contribute calendar blocks to the editor palette

Full Changelog: https://github.com/ernestdefoe/calendar/compare/2.0.2...2.0.3

View release on GitHub

calendar 2.0.4

What's Changed

• fix(security): don't serve unpublished events from the single-event iCal endpoint
• fix: address remaining Floxum code-review findings

Full Changelog: https://github.com/ernestdefoe/calendar/compare/2.0.3...2.0.4

View release on GitHub

calendar 2.0.5

Security

• Draft events are no longer publicly readable. Single-event endpoint now 404s for unpublished events unless you're an event manager or the author. (#2)

Fixes

• Event & category slug creation no longer 500s under a concurrent same-title race — it retries with a fresh suffix. (#3)

Performance

• Cap expanded recurring occurrences and lower the listing row limit so a dense calendar can't spike memory/CPU. (#4)

Housekeeping

• Remove an unused constant (#5); resolve the FoF Upload check lazily per-request instead of at parse time (#6); log instead of silently swallowing that detection failure (#7).

View release on GitHub

calendar 2.0.6

Security + hardening release (Floxum re-audit fixes).

• Security (HIGH): event URLs are now scheme-allowlisted (http/https) — javascript:/data: URLs can no longer be stored and rendered as an <a href> (stored-XSS fix), with a matching guard in the event detail modal.
• Security: RSVP is restricted to published events (or the author's own draft) — a guessed draft ID can't have its RSVP counts polluted.
• Performance: indexed users.cal_birthday (was a full table scan on the celebrations widget); the iCal feed eager-loads category + user to avoid N+1 during serialisation.
• Conventions: resolve() moved out of the schema getter into the fields builder.
• Refactor: CalendarPage split into focused MonthGrid / TimeGrid / EventListView components (no functional change; verified across month/week/list views).

View release on GitHub

calendar 2.1.0

What's Changed

New: attendee roster on events

• Event details now list Who's going and Also interested with avatar chips.
• When the armory extension is installed, each attendee's best character (main first, then highest item level) is shown in official class color with spec and item level — perfect for raid signups.
• Roster is delivered via the show/RSVP endpoints; the list endpoint stays lean.

Maintenance

• CalendarPage split into MonthGrid / TimeGrid / EventListView components (audit follow-up).

Full Changelog: https://github.com/ernestdefoe/calendar/compare/2.0.6...2.1.0

View release on GitHub

calendar v2.2.0

New

• Hide the Calendar nav link — a new admin setting removes the Calendar entry from the sidebar navigation for forums that prefer a lean nav. The calendar stays reachable from the Upcoming Events widget and the /calendar URL.
• fof/forum-widgets-core support — if you run the FoF widget manager, Upcoming Events now registers as a managed widget: place and reorder it from the widget manager like any other widget (it renders flat, with its own header — no double chrome). The extension detects the widget core at runtime; forums without it keep the exact same behavior as before, and nothing new is required.

Update

php flarum cache:clear```

[View release on GitHub](https://github.com/ernestdefoe/calendar/releases/tag/v2.2.0)